APAddressBook: An Objective-C repository from Alty

APAddressBook is a wrapper on AddressBook.framework that gives easy access to native address book without pain in a head.

Features

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

Objective-c

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 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 in addressBook.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;
}

Swift

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'

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
        }
    })

Contacts

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.

Alterplay/APAddressBook

Features

Objective-c

Swift

APContact serialization

0.1.x to 0.2.x Migration guide

History

Contributor guide

Contacts