introducing the contacts framework · partial contacts let keystofetch = [cncontactgivennamekey,...

© 2015 Apple Inc. All rights reserved. Redistribution or public display not permitted without written permission from Apple.

#WWDC15

Introducing the Contacts FrameworkFor OS X, iOS, and watchOS

Bruce Stadnyk iOS Contacts EngineerDave Dribin OS X Contacts EngineerJulien Robert iOS Contacts Engineer

App Frameworks

Session 223

What is Contacts Framework?


Objective-C and Swift API


Objective-C and Swift APIOptimized for thread-safe, read only usage


Objective-C and Swift APIOptimized for thread-safe, read only usageOne API, multiple platforms


Objective-C and Swift APIOptimized for thread-safe, read only usageOne API, multiple platformsAddressBook API being deprecated

What are Contacts?

What are Contacts?

Everyone has Contacts

What are Contacts?

Everyone has Contacts Phone, Mail, Messages, …

What are Contacts?

Everyone has Contacts Phone, Mail, Messages, … Central to the user experience

Contact Properties

Contact Properties

John

Appleseed

[email protected] (home)

[email protected] (work)

(408) 555-0126 (iPhone)

Contact Properties

contact.imageData

contact.givenName

contact.familyName

contact.emailAddresses

contact.phoneNumbers

John

Appleseed



(408) 555-0126 (iPhone)

Contact Objects

Contact Objects

CNContact

Contact Objects

CNContact

CNMutableContact

Contact Objects

CNContact

CNMutableContact

CNLabeledValue

Creating a New Contact

import Contacts


import Contacts // create mutable for adding to the contact let contact = CNMutableContact()


import Contacts // create mutable for adding to the contact let contact = CNMutableContact() contact.imageData = // profile picture as NSData


import Contacts // create mutable for adding to the contact let contact = CNMutableContact() contact.imageData = // profile picture as NSData contact.givenName = "John" contact.familyName = "Appleseed"

Creating a New ContactLabeled Values

let homeEmail = CNLabeledValue(label: CNLabelHome, value: "[email protected]") let workEmail = CNLabeledValue(label: CNLabelWork, value: "[email protected]")

mailto:[email protected]



contact.emailAddresses = [homeEmail, workEmail]



contact.emailAddresses = [homeEmail, workEmail]

contact.phoneNumbers = [CNLabeledValue( label: CNLabelPhoneNumberiPhone, value: CNPhoneNumber(stringValue: "(408) 555-0126"))]


let address = CNMutablePostalAddress() address.street = "774 Loma Vista Ave" address.city = "Los Gatos" address.state = "CA" address.postalCode = "95032"


let address = CNMutablePostalAddress() address.street = "774 Loma Vista Ave" address.city = "Los Gatos" address.state = "CA" address.postalCode = "95032"

contact.postalAddresses = [CNLabeledValue(label: CNLabelHome, value: address)]

Creating a New ContactDates

let birthday = NSDateComponents() birthday.day = 1 birthday.month = 4 birthday.year = 1988 // can omit for a year-less birthday

Creating a New ContactDates

let birthday = NSDateComponents() birthday.day = 1 birthday.month = 4 birthday.year = 1988 // can omit for a year-less birthday

contact.birthday = birthday

Formatting Contact Data


let fullName = CNContactFormatter.stringFromContact(contact, style: .FullName)


let fullName = CNContactFormatter.stringFromContact(contact, style: .FullName) print(fullName) // John Appleseed



let postalString = CNPostalAddressFormatter.stringFromPostalAddress(address)



let postalString = CNPostalAddressFormatter.stringFromPostalAddress(address) print(postalString) // 774 Loma Vista Ave // Los Gatos, CA 95032

Using Contacts in Your App

Dave Dribin OS X Contacts Engineer

Using Contacts in Your App

CNContactStore

Fetching User's Contacts

class CNContactStore : NSObject {

func unifiedContactsMatchingPredicate(

predicate: NSPredicate,

keysToFetch: [CNKeyDescriptor]) -> [CNContact] throws

...

}

Predicateslet predicate = CNContact.predicateForContactsMatchingName("Appleseed")

Predicateslet predicate = CNContact.predicateForContactsMatchingName("Appleseed")

John

Appleseed

[email protected] (home)[email protected] (work)

(408) 555-0126 (iPhone)

April 1, 1988 (birthday)

Jane

Appleseed


(505) 555-0155 (home)(408) 555-0166 (work)

Craig

Bromley


(465) 555-0199 (iPhone)

Jun 21 (birthday)

Keys to Fetchlet keysToFetch = ["givenName", "familyName"]

imageData

givenName

familyName

emailAddresses

phoneNumbers

birthday

Jane

Appleseed


(505) 555-0155 (home)(408) 555-0166 (work)

John

Appleseed


(408) 555-0126 (iPhone)


Keys to Fetchlet keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]

imageData

givenName

familyName

emailAddresses

phoneNumbers

birthday

John

Appleseed


(408) 555-0126 (iPhone)


Jane

Appleseed


(505) 555-0155 (home)(408) 555-0166 (work)

How to Fetch

let predicate = CNContact.predicateForContactsMatchingName("Appleseed") let keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]

How to Fetch


let store = CNContactStore() let contacts = try store.unifiedContactsMatchingPredicate(predicate, keysToFetch: keysToFetch)

How to Fetch


let store = CNContactStore() let contacts = try store.unifiedContactsMatchingPredicate(predicate, keysToFetch: keysToFetch)

for contact in contacts { print("\(contact.givenName) \(contact.familyName)") }

Keeping UI ResponsiveMain Queue Background Queue

Fetch Contacts

CNContactCNContactCNContact

Keeping UI ResponsiveMain Queue Background Queue

Fetch Contacts



Data Privacy

Data Privacyclass CNContactStore : NSObject { func requestAccessForEntityType(..., completionHandler:) }

Privacy and Your App Pacific Heights Tuesday 2:30PM

Partial Contactslet keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]

John

Appleseed


(408) 555-0126 (iPhone)


John givenName

Appleseed familyName


(408) 555-0126 (iPhone)


Partial Contactslet keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]

John givenName


phoneNumbers


(408) 555-0126 (iPhone)


John

Appleseed


(408) 555-0126 (iPhone)


Partial Contacts

if (contact.isKeyAvailable(CNContactPhoneNumbersKey)) { print("\(contact.phoneNumbers)") }

Partial Contacts

if (contact.isKeyAvailable(CNContactPhoneNumbersKey)) { print("\(contact.phoneNumbers)") } else { let keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactPhoneNumbersKey] var refetchedContact = try store.unifiedContactWithIdentifier( contact.identifier, keysToFetch: keysToFetch) print("\(refetchedContact.phoneNumbers)") }

Mr. namePrefix

John givenName

middleName


Sr. nameSuffix

Formatting Partial Contactslet keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]

Mr. namePrefix

John givenName

middleName


Sr. nameSuffix

Formatting Partial Contactslet keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey,

CNContactNamePrefixKey, CNContactMiddleNameKey, ...]

Formatting Partial Contacts

Mr. namePrefix

John givenName

middleName


Sr. nameSuffix

+ Any Others

let keysToFetch =

[CNContactFormatter.descriptorForRequiredKeysForStyle(.FullName)]

Key Descriptors

let predicate = CNContact.predicateForContactsMatchingName("Appleseed") let keysToFetch = [ CNContactFormatter.descriptorForRequiredKeysForStyle(.FullName), CNContactEmailAddressesKey]

Key Descriptors


let contacts = try store.unifiedContactsMatchingPredicate(predicate, keysToFetch: keysToFetch)

Key Descriptors


let contacts = try store.unifiedContactsMatchingPredicate(predicate, keysToFetch: keysToFetch)

for contact in contacts { let fullName = CNContactFormatter.stringFromContact( contact, style: .FullName) ?? "No Name" print("\(fullName): \(contact.emailAddresses)") }

Unified Contacts

John

Appleseed


(408) 555-0126 (iPhone)

iCloud

John

Appleseed



Facebook

John

Appleseed

[email protected] (work) [email protected] (home)

(408) 555-0126 (iPhone)


Unified

Unified Contacts

John

Appleseed


(408) 555-0126 (iPhone)

iCloud

John

Appleseed



Facebook

Adding a New Contact

let john = CNMutableContact() john.givenName = "John" john.familyName = "Appleseed"

let john = CNMutableContact() john.givenName = "John" john.familyName = "Appleseed"

let saveRequest = CNSaveRequest() saveRequest.addContact(john, toContainerWithIdentifier: nil) try store.executeSaveRequest(saveRequest)

Adding a New Contact

Updating an Existing Contact

let updatedContact = contact.mutableCopy() let newEmail = CNLabeledValue(label: CNLabelHome, value: "[email protected]") updatedContact.emailAddresses.append(newEmail)

Updating an Existing Contact

let updatedContact = contact.mutableCopy() let newEmail = CNLabeledValue(label: CNLabelHome, value: "[email protected]") updatedContact.emailAddresses.append(newEmail)

let saveRequest = CNSaveRequest() saveRequest.updateContact(updatedContact) try store.executeSaveRequest(saveRequest)

Contacts in the UI

Julien Robert iOS Contacts Engineer

ContactsUINew framework


iOS OS X


iOS OS X

CNContactPickerViewController CNContactPicker


iOS OS X

CNContactPickerViewController CNContactPicker

CNContactViewController CNContactViewController

Picking ContactsCNContactPickerViewController


Modern replacement for ABPeoplePickerNavigationController


Modern replacement for ABPeoplePickerNavigationControllerMust be presented, not pushed


Modern replacement for ABPeoplePickerNavigationControllerMust be presented, not pushedAlways out of process, no contacts access dialog


Modern replacement for ABPeoplePickerNavigationControllerMust be presented, not pushedAlways out of process, no contacts access dialogMay return partial contacts


Modern replacement for ABPeoplePickerNavigationControllerMust be presented, not pushedAlways out of process, no contacts access dialogMay return partial contactsBehavior based on delegate methods and predicates


Modern replacement for ABPeoplePickerNavigationControllerMust be presented, not pushedAlways out of process, no contacts access dialogMay return partial contactsBehavior based on delegate methods and predicatesSupports multi-selection

Picking ContactsDelegate methods


Single contact


Single contact contactPicker(picker, didSelectContact contact: CNContact)



Single propertycontactPicker(picker, didSelectContactProperty property: CNContactProperty)



Single propertycontactPicker(picker, didSelectContactProperty property: CNContactProperty)

class CNContactProperty { var contact: CNContact var key: NSString var value: AnyObject? var identifier: NSString? }


Multiple contacts


Multiple contactscontactPicker(picker, didSelectContacts contacts: [CNContact])


Multiple contactscontactPicker(picker, didSelectContacts contacts: [CNContact])

Multiple propertiescontactPicker(picker, didSelectContactProperties properties: [CNContactProperty])

Picking ContactsPredicates


predicateForEnablingContact

• Which contacts are available• Evaluated on CNContact




let predicate = NSPredicate(format: "familyName LIKE[cd] 'parker'")




let predicate = NSPredicate(format: "familyName LIKE[cd] 'parker'")

contactPicker.predicateForEnablingContact = predicate


predicateForSelectionOfContact

• Which contacts are returned when tapped, others push the card




predicateForSelectionOfProperty

• Which properties are returned when tapped, others perform the default action• Evaluated on CNContactProperty




predicateForSelectionOfProperty

• Which properties are returned when tapped, others perform the default action• Evaluated on CNContactProperty

Coherence between predicates and delegate methods

Viewing ContactsCNContactViewController


One class to replace• ABPersonViewController

• ABNewPersonViewController

• ABUnknownPersonViewController


Use appropriate creation method


Use appropriate creation method• viewControllerForContact:



• viewControllerForNewContact:




• viewControllerForUnknownContact:





Always out of process





Always out of processContact must be fetched with descriptorForRequiredKeys

Viewing ContactsExample

let contact = try contactStore.unifiedContactWithIdentifier(identifier,keysToFetch: [CNContactViewController.descriptorForRequiredKeys])



let viewController = CNContactViewController(forContact: contact)




viewController.contactStore = self.contactStore viewController.delegate = self





self.pushViewController(viewController)





self.pushViewController(viewController)

func contactViewController(vc, didCompleteWithContact: contact) { // do something with the modified contact }

DemoPicking and Viewing Contacts

Meow

A new modern Contacts APICommon across all platforms Adopt now!

Summary

More Information

DocumentationContacts Framework ReferenceContactsUI Framework Referencehttp://developer.apple.com/library

Technical SupportApple Developer Forumshttp://developer.apple.com/forums

General InquiriesPaul Marcos, App Frameworks [email protected]

Labs

Contacts, Calendar and Reminders Lab Frameworks Lab A Thursday 4:30PM

Contacts, Calendar and Reminders Lab Frameworks Lab A Friday 9:00AM

introducing the contacts framework · partial contacts let keystofetch = [cncontactgivennamekey,...

Documents