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 via Cocoapods
Add APAddressBook pod to Podfile
pod 'APAddressBook'Installation via Carthage
Add to your Cartfile
github 'Alterplay/APAddressBook'Run carthage update to fetch and build the framework. Add APAddressBook.framework to your project's 'Linked Frameworks and Libraries'. Ensure that $(SRCROOT)/Carthage/Build/iOS/APAddressBook.framework is part of the carthage copy-framework build phase.
Warning for iOS 10.0 and after
To protect user privacy, an iOS app linked on or after iOS 10.0, and which accesses the user’s contacts, must statically declare the intent to do so. Include the NSContactsUsageDescription key in your app’s Info.plist file and provide a purpose string for this key. If your app attempts to access the user’s contacts without a corresponding purpose string, your app exits.
From here.
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
- APContactFieldAddressesWithLabels - array of contact addresses with original and localized labels
- APContactFieldAddressesOnly - array of contact addresses disregarding addresses labels
- 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
- APContactFieldDates - contact dates with localized and original labels
- APContactFieldRecordDate - contact record creation date and modification date
- APContactFieldDefault - contact name and phones without labels
- APContactFieldAll - all contact fields described above
Contact
recordIDproperty 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;
}];
APContactinstance 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 via Cocoapods
pod 'APAddressBook/Swift'Import APAddressBook-Bridging.h to application's objective-c bridging file.
#import <APAddressBook/APAddressBook-Bridging.h>Installation via Carthage
Add to your Cartfile
github 'Alterplay/APAddressBook'Run carthage update to fetch and build the framework. Add APAddressBook.framework to your project's 'Linked Frameworks and Libraries'. Ensure that $(SRCROOT)/Carthage/Build/iOS/APAddressBook.framework is part of the carthage copy-framework build phase.
Example
See example application in Example/Swift directory.
self.addressBook.loadContacts(
{ (contacts: [APContact]?, error: Error?) in
if let uwrappedContacts = contacts {
// do something with contacts
}
else if let unwrappedError = error {
// show error
}
})Use APContact-EasyMapping by Jean Lebrument
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent