APAddressBook

Easy access to iOS address book

Code Quality Rank: L5

Programming language: Objective-C

License: MIT License

Tags: UI    

Latest version: v0.3.2

README

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'

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

APContact serialization

Use APContact-EasyMapping by Jean Lebrument

0.1.x to 0.2.x Migration guide

Migration Guide

History

Releases

Contributor guide

Contributor Guide

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.