APAddressBook is a wrapper on AddressBook.framework that gives easy access to native address book without pain in a head.
- Load contacts from iOS address book asynchronously
- Decide what contact data fields you need to load (for example, only name and phone number)
- Filter contacts to get only necessary records (for example, you need only contacts with email)
- Sort contacts with array of any NSSortDescriptor
- Get photo of contact
Installation
Add APAddressBook
pod to Podfile
pod 'APAddressBook'
Load contacts
APAddressBook *addressBook = [[APAddressBook alloc] init];
// don't forget to show some activity
[addressBook loadContacts:^(NSArray <APContact *> *contacts, NSError *error)
{
// hide activity
if (!error)
{
// do something with contacts array
}
else
{
// show error
}
}];
Callback block will be run on main queue! If you need to run callback block on custom queue use
loadContactsOnQueue:completion:
method
Select contact fields bit-mask
Available fields:
- APContactFieldName - first name, last name, middle name, composite name
- APContactFieldJob - company (organization), job title
- APContactFieldThumbnail - thumbnail image
- APContactFieldPhonesOnly - array of phone numbers disregarding phone labels
- APContactFieldPhonesWithLabels - array phones with original and localized labels
- APContactFieldEmailsOnly - array of email addresses disregarding email labels
- APContactFieldEmailsWithLabels - array of email addresses with original and localized labels
- APContactFieldAddresses - array of contact addresses
- APContactFieldSocialProfiles - array of contact profiles in social networks
- APContactFieldBirthday - date of birthday
- APContactFieldWebsites - array of strings with website URLs
- APContactFieldNote - string with notes
- APContactFieldRelatedPersons - array of related persons
- APContactFieldLinkedRecordIDs - array of contact linked records IDs
- APContactFieldSource - contact source ID and source name
- APContactFieldRecordDate - contact record creation date and modification date
- APContactFieldDefault - contact name and phones without labels
- APContactFieldAll - all contact fields described above
Contact
recordID
property is always available
Example of field mask with name and thumbnail:
APAddressBook *addressBook = [[APAddressBook alloc] init];
addressBook.fieldsMask = APContactFieldFirstName | APContactFieldThumbnail;
Filter contacts
The most common use of this option is to filter contacts without phone number. Example:
addressBook.filterBlock = ^BOOL(APContact *contact)
{
return contact.phones.count > 0;
};
Sort contacts
APAddressBook returns unsorted contacts. So, most of users would like to sort contacts by first name and last name.
addressBook.sortDescriptors = @[
[NSSortDescriptor sortDescriptorWithKey:@"name.firstName" ascending:YES],
[NSSortDescriptor sortDescriptorWithKey:@"name.lastName" ascending:YES]
];
Load contact by address book record ID
[addressBook loadContactByRecordID:recordID completion:^(APContact *contact)
{
self.contact = contact;
}];
APContact
instance will contain fields that set inaddressBook.fieldsMask
Callback block will be run on main queue! If you need to run callback block on custom queue use
loadContactByRecordID:onQueue:completion:
method
** Load contact photo by address book record ID **
[addressBook loadPhotoByRecordID:recordID completion:^(UIImage *image)
{
self.imageView.image = image;
}];
Callback block will be run on main queue! If you need to run callback block on custom queue use
loadPhotoByRecordID:onQueue:completion:
method
Observe address book external changes
// start observing
[addressBook startObserveChangesWithCallback:^
{
// reload contacts
}];
// stop observing
[addressBook stopObserveChanges];
Request address book access
[addressBook requestAccess:^(BOOL granted, NSError *error)
{
// check `granted`
}];
Check address book access
switch([APAddressBook access])
{
case APAddressBookAccessUnknown:
// Application didn't request address book access yet
break;
case APAddressBookAccessGranted:
// Access granted
break;
case APAddressBookAccessDenied:
// Access denied or restricted by privacy settings
break;
}
Installation
pod 'APAddressBook/Swift'
Import APAddressBook-Bridging.h
to application's objective-c bridging file.
#import <APAddressBook/APAddressBook-Bridging.h>
Example
See example application in Example/Swift
directory.
self.addressBook.loadContacts(
{ (contacts: [APContact]?, error: NSError?) in
if let uwrappedContacts = contacts {
// do something with contacts
}
else if let unwrappedError = error {
// show error
}
})
If you have improvements or concerns, feel free to post an issue and write details.
Check out all Alterplay's GitHub projects. Email us with other ideas and projects.