contacts-framework

Name: contacts-framework
Author: dpearson2699

915stars45forks

How to install contacts-framework?

dpearson2699/swift-ios-skills/contacts-framework

$npx -y skills add dpearson2699/swift-ios-skills --skill contacts-framework

Installs into the current project.

Summary

Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks. Use when fetching contact data, saving new contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests.

Files · 1

View on GitHub

SKILL.md

1	# Contacts Framework
2
3	Use `CNContactStore`, `CNSaveRequest`, and `CNContactPickerViewController` to
4	fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps.
5
6	## Contents
7
8	- [Setup](#setup)
9	- [Authorization](#authorization)
10	- [Fetching Contacts](#fetching-contacts)
11	- [Key Descriptors](#key-descriptors)
12	- [Creating and Updating Contacts](#creating-and-updating-contacts)
13	- [Contact Picker](#contact-picker)
14	- [Observing Changes](#observing-changes)
15	- [Common Mistakes](#common-mistakes)
16	- [Review Checklist](#review-checklist)
17	- [References](#references)
18
19	## Setup
20
21	### Project Configuration
22
23	1. Add `NSContactsUsageDescription` to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
24	2. No additional capability or entitlement is required for ordinary Contacts access.
25	3. Add `com.apple.developer.contacts.notes` only when reading or writing `CNContactNoteKey` / `CNContact.note`; this entitlement requires Apple approval before public distribution.
26
27	### Imports
28
29	```swift
30	@preconcurrency import Contacts // CNContactStore, CNSaveRequest, CNContact
31	import ContactsUI // CNContactPickerViewController
32	```
33
34	## Authorization
35
36	Request access before fetching or saving contacts. The picker (`CNContactPickerViewController`)
37	does not require authorization -- the system grants access only to the contacts
38	the user selects.
39
40	```swift
41	let store = CNContactStore()
42
43	func requestAccess() async throws -> Bool {
44	return try await store.requestAccess(for: .contacts)
45	}
46
47	// Check current status without prompting
48	func checkStatus() -> CNAuthorizationStatus {
49	CNContactStore.authorizationStatus(for: .contacts)
50	}
51	```
52
53	### Authorization States
54
55	\| Status \| Meaning \|
56	\|---\|---\|
57	\| `.notDetermined` \| User has not been prompted yet \|
58	\| `.authorized` \| Full read/write access granted \|
59	\| `.denied` \| User denied access; direct to Settings \|
60	\| `.restricted` \| Parental controls or MDM restrict access \|
61	\| `.limited` \| iOS 18+: user granted access to selected contacts only \|
62
63	Treat both `.authorized` and `.limited` as usable Contacts API states. With
64	`.limited`, fetch, edit, and delete operations only apply to contacts the user
65	granted or the app created. Use `ContactAccessButton` or
66	`contactAccessPicker(isPresented:completionHandler:)` to let users add contacts
67	to the app's limited-access set.
68
69	## Fetching Contacts
70
71	Use `unifiedContacts(matching:keysToFetch:)` for predicate-based queries.
72	Use `enumerateContacts(with:usingBlock:)` for batch enumeration of all contacts.
73	For large cached address books, first fetch identifiers, then fetch detailed
74	contacts in batches by identifier.
75
76	### Fetch by Name
77
78	```swift
79	func fetchContacts(named name: String) throws -> [CNContact] {
80	let predicate = CNContact.predicateForContacts(matchingName: name)
81	let keys: [CNKeyDescriptor] = [
82	CNContactGivenNameKey as CNKeyDescriptor,
83	CNContactFamilyNameKey as CNKeyDescriptor,
84	CNContactPhoneNumbersKey as CNKeyDescriptor
85	]
86	return try store.unifiedContacts(matching: predicate, keysToFetch: keys)
87	}
88	```
89
90	### Fetch by Identifier
91
92	```swift
93	func fetchContact(identifier: String) throws -> CNContact {
94	let keys: [CNKeyDescriptor] = [
95	CNContactGivenNameKey as CNKeyDescriptor,
96	CNContactFamilyNameKey as CNKeyDescriptor,
97	CNContactEmailAddressesKey as CNKeyDescriptor
98	]
99	return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
100	}
101	```
102
103	### Enumerate All Contacts
104
105	Perform I/O-heavy enumeration off the main thread.
106
107	```swift
108	func fetchAllContacts() throws -> [CNContact] {
109	let keys: [CNKeyDescriptor] = [
110	CNContactGivenNameKey as CNKeyDescriptor,
111	CNContactFamilyNameKey as CNKeyDescriptor
112	]
113	let request = CNContactFetchRequest(keysToFetch: keys)
114	request.sortOrder = .givenName
115
116	var contacts: [CNContact] = []
117	try store.enumerateContacts(with: request) { contact, _ in
118	contacts.append(contact)
119	}
120	return contacts
121	}
122	```
123
124	## Key Descriptors
125
126	Only fetch the properties you need. Accessing an unfetched property throws
127	`CNContactPropertyNotFetchedException`.
128
129	### Common Keys
130
131	\| Key \| Property \|
132	\|---\|---\|
133	\| `CNContactGivenNameKey` \| First name \|
134	\| `CNContactFamilyNameKey` \| Last name \|
135	\| `CNContactPhoneNumbersKey` \| Phone numbers array \|
136	\| `CNContactEmailAddressesKey` \| Email addresses array \|
137	\| `CNContactPostalAddressesKey` \| Mailing addresses array \|
138	\| `CNContactImageDataKey` \| Full-resolution contact photo \|
139	\| `CNContactThumbnailImageDataKey` \| Thumbnail contact photo \|
140	\| `CNContactBirthdayKey` \| Birthday date components \|
141	\| `CNContactOrganizationNameKey` \|

People who liked this also viewed

6 picks

Type

contacts-framework

915stars45forks

View on GitHub

How to install contacts-framework?

dpearson2699/swift-ios-skills/contacts-framework

$npx -y skills add dpearson2699/swift-ios-skills --skill contacts-framework

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Contacts Framework
2
3	Use `CNContactStore`, `CNSaveRequest`, and `CNContactPickerViewController` to
4	fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps.
5
6	## Contents
7
8	- [Setup](#setup)
9	- [Authorization](#authorization)
10	- [Fetching Contacts](#fetching-contacts)
11	- [Key Descriptors](#key-descriptors)
12	- [Creating and Updating Contacts](#creating-and-updating-contacts)
13	- [Contact Picker](#contact-picker)
14	- [Observing Changes](#observing-changes)
15	- [Common Mistakes](#common-mistakes)
16	- [Review Checklist](#review-checklist)
17	- [References](#references)
18
19	## Setup
20
21	### Project Configuration
22
23	1. Add `NSContactsUsageDescription` to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
24	2. No additional capability or entitlement is required for ordinary Contacts access.
25	3. Add `com.apple.developer.contacts.notes` only when reading or writing `CNContactNoteKey` / `CNContact.note`; this entitlement requires Apple approval before public distribution.
26
27	### Imports
28
29	```swift
30	@preconcurrency import Contacts // CNContactStore, CNSaveRequest, CNContact
31	import ContactsUI // CNContactPickerViewController
32	```
33
34	## Authorization
35
36	Request access before fetching or saving contacts. The picker (`CNContactPickerViewController`)
37	does not require authorization -- the system grants access only to the contacts
38	the user selects.
39
40	```swift
41	let store = CNContactStore()
42
43	func requestAccess() async throws -> Bool {
44	return try await store.requestAccess(for: .contacts)
45	}
46
47	// Check current status without prompting
48	func checkStatus() -> CNAuthorizationStatus {
49	CNContactStore.authorizationStatus(for: .contacts)
50	}
51	```
52
53	### Authorization States
54
55	\| Status \| Meaning \|
56	\|---\|---\|
57	\| `.notDetermined` \| User has not been prompted yet \|
58	\| `.authorized` \| Full read/write access granted \|
59	\| `.denied` \| User denied access; direct to Settings \|
60	\| `.restricted` \| Parental controls or MDM restrict access \|
61	\| `.limited` \| iOS 18+: user granted access to selected contacts only \|
62
63	Treat both `.authorized` and `.limited` as usable Contacts API states. With
64	`.limited`, fetch, edit, and delete operations only apply to contacts the user
65	granted or the app created. Use `ContactAccessButton` or
66	`contactAccessPicker(isPresented:completionHandler:)` to let users add contacts
67	to the app's limited-access set.
68
69	## Fetching Contacts
70
71	Use `unifiedContacts(matching:keysToFetch:)` for predicate-based queries.
72	Use `enumerateContacts(with:usingBlock:)` for batch enumeration of all contacts.
73	For large cached address books, first fetch identifiers, then fetch detailed
74	contacts in batches by identifier.
75
76	### Fetch by Name
77
78	```swift
79	func fetchContacts(named name: String) throws -> [CNContact] {
80	let predicate = CNContact.predicateForContacts(matchingName: name)
81	let keys: [CNKeyDescriptor] = [
82	CNContactGivenNameKey as CNKeyDescriptor,
83	CNContactFamilyNameKey as CNKeyDescriptor,
84	CNContactPhoneNumbersKey as CNKeyDescriptor
85	]
86	return try store.unifiedContacts(matching: predicate, keysToFetch: keys)
87	}
88	```
89
90	### Fetch by Identifier
91
92	```swift
93	func fetchContact(identifier: String) throws -> CNContact {
94	let keys: [CNKeyDescriptor] = [
95	CNContactGivenNameKey as CNKeyDescriptor,
96	CNContactFamilyNameKey as CNKeyDescriptor,
97	CNContactEmailAddressesKey as CNKeyDescriptor
98	]
99	return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
100	}
101	```
102
103	### Enumerate All Contacts
104
105	Perform I/O-heavy enumeration off the main thread.
106
107	```swift
108	func fetchAllContacts() throws -> [CNContact] {
109	let keys: [CNKeyDescriptor] = [
110	CNContactGivenNameKey as CNKeyDescriptor,
111	CNContactFamilyNameKey as CNKeyDescriptor
112	]
113	let request = CNContactFetchRequest(keysToFetch: keys)
114	request.sortOrder = .givenName
115
116	var contacts: [CNContact] = []
117	try store.enumerateContacts(with: request) { contact, _ in
118	contacts.append(contact)
119	}
120	return contacts
121	}
122	```
123
124	## Key Descriptors
125
126	Only fetch the properties you need. Accessing an unfetched property throws
127	`CNContactPropertyNotFetchedException`.
128
129	### Common Keys
130
131	\| Key \| Property \|
132	\|---\|---\|
133	\| `CNContactGivenNameKey` \| First name \|
134	\| `CNContactFamilyNameKey` \| Last name \|
135	\| `CNContactPhoneNumbersKey` \| Phone numbers array \|
136	\| `CNContactEmailAddressesKey` \| Email addresses array \|
137	\| `CNContactPostalAddressesKey` \| Mailing addresses array \|
138	\| `CNContactImageDataKey` \| Full-resolution contact photo \|
139	\| `CNContactThumbnailImageDataKey` \| Thumbnail contact photo \|
140	\| `CNContactBirthdayKey` \| Birthday date components \|
141	\| `CNContactOrganizationNameKey` \|

People who liked this also viewed

6 picks

Type