📇 Contacts

⭐ Difficulty: ⭐⭐ ⏱️ Est. Time: 1h 📂 App Services

iOS 연락처 데이터에 안전하게 접근하고 관리하기

iOS 9+

✨ Contacts Framework?

The Contacts framework provides APIs for safely accessing the user's contact database. It supports querying, creating, editing, and deleting contacts, managed centrally through CNContactStore. User authorization is required, with privacy as the top priority.

💡 Key Features: Contact Lookup · Create/Edit/Delete Contacts · Group Management · Contact Formatting · Contact Picker UI · Change Observation · Batch Saving

🔑 1. 권한 요청

User authorization is required for contact access. Both Info.plist settings and runtime permission requests are needed.

Info.plist — Add Permission Descriptions

// Info.plist에 추가
NSContactsUsageDescription
"연락처에 접근하여 친구를 초대하고 정보를 공유합니다"

ContactsManager.swift — Permission Management

import Contacts

@Observable
class ContactsManager {
    let store = CNContactStore()
    var authorizationStatus: CNAuthorizationStatus = .notDetermined

    // 현재 권한 상태 확인
    func checkAuthorizationStatus() {
        authorizationStatus = CNContactStore.authorizationStatus(for: .contacts)
    }

    // 권한 요청
    func requestAccess() async -> Bool {
        do {
            let granted = try await store.requestAccess(for: .contacts)
            await MainActor.run {
                authorizationStatus = granted ? .authorized : .denied
            }
            return granted
        } catch {
            print("권한 요청 오류: \(error)")
            return false
        }
    }

    // 권한 상태에 따른 처리
    func ensureAuthorization() async -> Bool {
        checkAuthorizationStatus()

        switch authorizationStatus {
        case .authorized:
            return true
        case .notDetermined:
            return await requestAccess()
        case .denied, .restricted:
            return false
        @unknown default:
            return false
        }
    }
}

🔍 2. 연락처 조회

다양한 방법으로 연락처를 검색하고 조회.

ContactsFetcher.swift — Contact Query

import Contacts

extension ContactsManager {
    // 모든 연락처 가져오기
    func fetchAllContacts() throws -> [CNContact] {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactGivenNameKey as CNKeyDescriptor,
            CNContactFamilyNameKey as CNKeyDescriptor,
            CNContactPhoneNumbersKey as CNKeyDescriptor,
            CNContactEmailAddressesKey as CNKeyDescriptor,
            CNContactImageDataKey as CNKeyDescriptor,
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
        ]

        let request = CNContactFetchRequest(keysToFetch: keysToFetch)
        var contacts: [CNContact] = []

        try store.enumerateContacts(with: request) { contact, stop in
            contacts.append(contact)
        }

        return contacts
    }

    // 이름으로 연락처 검색
    func searchContacts(name: String) throws -> [CNContact] {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
            CNContactPhoneNumbersKey as CNKeyDescriptor,
            CNContactEmailAddressesKey as CNKeyDescriptor
        ]

        let predicate = CNContact.predicateForContacts(matchingName: name)
        return try store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)
    }

    // 식별자로 연락처 가져오기
    func fetchContact(identifier: String) throws -> CNContact {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
            CNContactPhoneNumbersKey as CNKeyDescriptor,
            CNContactEmailAddressesKey as CNKeyDescriptor,
            CNContactPostalAddressesKey as CNKeyDescriptor,
            CNContactBirthdayKey as CNKeyDescriptor,
            CNContactImageDataKey as CNKeyDescriptor
        ]

        let predicate = CNContact.predicateForContacts(withIdentifiers: [identifier])
        let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)

        guard let contact = contacts.first else {
            throw ContactsError.contactNotFound
        }

        return contact
    }

    // 전화번호로 연락처 검색
    func searchByPhoneNumber(_ phoneNumber: String) throws -> [CNContact] {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
            CNContactPhoneNumbersKey as CNKeyDescriptor
        ]

        let allContacts = try fetchAllContacts()

        return allContacts.filter { contact in
            contact.phoneNumbers.contains { labeledValue in
                labeledValue.value.stringValue.contains(phoneNumber)
            }
        }
    }
}

enum ContactsError: Error {
    case contactNotFound
    case unauthorized
    case saveFailed
}

➕ 3. 연락처 생성

새로운 연락처를 만들고 저장.

ContactsCreator.swift — Create Contacts

import Contacts

extension ContactsManager {
    // 새 연락처 생성
    func createContact(
        givenName: String,
        familyName: String,
        phoneNumbers: [String] = [],
        emails: [String] = []
    ) throws {
        let contact = CNMutableContact()

        // 이름 설정
        contact.givenName = givenName
        contact.familyName = familyName

        // 전화번호 추가
        contact.phoneNumbers = phoneNumbers.map { number in
            CNLabeledValue(
                label: CNLabelPhoneNumberMobile,
                value: CNPhoneNumber(stringValue: number)
            )
        }

        // 이메일 추가
        contact.emailAddresses = emails.map { email in
            CNLabeledValue(
                label: CNLabelHome,
                value: email as NSString
            )
        }

        // 연락처 저장
        let saveRequest = CNSaveRequest()
        saveRequest.add(contact, toContainerWithIdentifier: nil)

        try store.execute(saveRequest)
    }

    // 상세 정보와 함께 연락처 생성
    func createDetailedContact(
        givenName: String,
        familyName: String,
        organizationName: String? = nil,
        jobTitle: String? = nil,
        phoneNumbers: [(String, String)] = [], // (label, number)
        emails: [(String, String)] = [], // (label, email)
        postalAddress: CNPostalAddress? = nil,
        birthday: DateComponents? = nil,
        note: String? = nil
    ) throws {
        let contact = CNMutableContact()

        // 기본 정보
        contact.givenName = givenName
        contact.familyName = familyName
        contact.organizationName = organizationName ?? ""
        contact.jobTitle = jobTitle ?? ""

        // 전화번호
        contact.phoneNumbers = phoneNumbers.map { label, number in
            CNLabeledValue(
                label: label,
                value: CNPhoneNumber(stringValue: number)
            )
        }

        // 이메일
        contact.emailAddresses = emails.map { label, email in
            CNLabeledValue(
                label: label,
                value: email as NSString
            )
        }

        // 주소
        if let address = postalAddress {
            contact.postalAddresses = [
                CNLabeledValue(label: CNLabelHome, value: address)
            ]
        }

        // 생일
        contact.birthday = birthday

        // 메모
        contact.note = note ?? ""

        // 저장
        let saveRequest = CNSaveRequest()
        saveRequest.add(contact, toContainerWithIdentifier: nil)
        try store.execute(saveRequest)
    }
}

✏️ 4. 연락처 수정 및 삭제

기존 연락처를 수정하거나 삭제.

ContactsEditor.swift — Edit/Delete Contacts

import Contacts

extension ContactsManager {
    // 연락처 수정
    func updateContact(
        identifier: String,
        givenName: String? = nil,
        familyName: String? = nil,
        phoneNumbers: [String]? = nil
    ) throws {
        // 기존 연락처 가져오기
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactGivenNameKey as CNKeyDescriptor,
            CNContactFamilyNameKey as CNKeyDescriptor,
            CNContactPhoneNumbersKey as CNKeyDescriptor
        ]

        let predicate = CNContact.predicateForContacts(withIdentifiers: [identifier])
        let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)

        guard let existingContact = contacts.first else {
            throw ContactsError.contactNotFound
        }

        // 변경 가능한 복사본 만들기
        let mutableContact = existingContact.mutableCopy() as! CNMutableContact

        // 수정
        if let givenName = givenName {
            mutableContact.givenName = givenName
        }

        if let familyName = familyName {
            mutableContact.familyName = familyName
        }

        if let phoneNumbers = phoneNumbers {
            mutableContact.phoneNumbers = phoneNumbers.map { number in
                CNLabeledValue(
                    label: CNLabelPhoneNumberMobile,
                    value: CNPhoneNumber(stringValue: number)
                )
            }
        }

        // 저장
        let saveRequest = CNSaveRequest()
        saveRequest.update(mutableContact)
        try store.execute(saveRequest)
    }

    // 연락처 삭제
    func deleteContact(identifier: String) throws {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactIdentifierKey as CNKeyDescriptor
        ]

        let predicate = CNContact.predicateForContacts(withIdentifiers: [identifier])
        let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)

        guard let contact = contacts.first else {
            throw ContactsError.contactNotFound
        }

        let mutableContact = contact.mutableCopy() as! CNMutableContact

        let saveRequest = CNSaveRequest()
        saveRequest.delete(mutableContact)
        try store.execute(saveRequest)
    }

    // 전화번호 추가
    func addPhoneNumber(to identifier: String, phoneNumber: String, label: String) throws {
        let keysToFetch: [CNKeyDescriptor] = [
            CNContactPhoneNumbersKey as CNKeyDescriptor
        ]

        let predicate = CNContact.predicateForContacts(withIdentifiers: [identifier])
        let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)

        guard let contact = contacts.first else {
            throw ContactsError.contactNotFound
        }

        let mutableContact = contact.mutableCopy() as! CNMutableContact

        // 새 전화번호 추가
        let newPhoneNumber = CNLabeledValue(
            label: label,
            value: CNPhoneNumber(stringValue: phoneNumber)
        )
        mutableContact.phoneNumbers.append(newPhoneNumber)

        let saveRequest = CNSaveRequest()
        saveRequest.update(mutableContact)
        try store.execute(saveRequest)
    }
}

📱 5. SwiftUI Integration — Contact Picker

Use the system contact picker in SwiftUI.

ContactPickerView.swift — Contact Picker

import SwiftUI
import ContactsUI

struct ContactPickerView: UIViewControllerRepresentable {
    @Binding var selectedContact: CNContact?
    @Environment(\.dismiss) var dismiss

    func makeUIViewController(context: Context) -> CNContactPickerViewController {
        let picker = CNContactPickerViewController()
        picker.delegate = context.coordinator

        // 표시할 속성 지정
        picker.displayedPropertyKeys = [
            CNContactPhoneNumbersKey,
            CNContactEmailAddressesKey
        ]

        return picker
    }

    func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}

    func makeCoordinator() -> Coordinator {
        Coordinator(selectedContact: $selectedContact, dismiss: dismiss)
    }

    class Coordinator: NSObject, CNContactPickerDelegate {
        @Binding var selectedContact: CNContact?
        let dismiss: DismissAction

        init(selectedContact: Binding<CNContact?>, dismiss: DismissAction) {
            _selectedContact = selectedContact
            self.dismiss = dismiss
        }

        // 연락처 선택 완료
        func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
            selectedContact = contact
            dismiss()
        }

        // 취소
        func contactPickerDidCancel(_ picker: CNContactPickerViewController) {
            dismiss()
        }
    }
}

// 사용 예제
struct ContactSelectorView: View {
    @State private var selectedContact: CNContact?
    @State private var showPicker = false

    var body: some View {
        VStack(spacing: 20) {
            if let contact = selectedContact {
                VStack(alignment: .leading, spacing: 8) {
                    Text(CNContactFormatter.string(from: contact, style: .fullName) ?? "알 수 없음")
                        .font(.headline)

                    if let phoneNumber = contact.phoneNumbers.first?.value.stringValue {
                        Text(phoneNumber)
                            .font(.subheadline)
                            .foregroundStyle(.secondary)
                    }
                }
                .padding()
                .background(Color.gray.opacity(0.1))
                .cornerRadius(8)
            } else {
                Text("연락처가 선택되지 않았습니다")
                    .foregroundStyle(.secondary)
            }

            Button("연락처 선택") {
                showPicker = true
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
        .sheet(isPresented: $showPicker) {
            ContactPickerView(selectedContact: $selectedContact)
        }
    }
}

🎨 6. 연락처 포맷팅

Display contact information using CNContactFormatter.

ContactFormatter.swift — Contact Formatting

import Contacts

class ContactFormatterHelper {
    // 전체 이름 포맷
    func formatFullName(_ contact: CNContact) -> String {
        return CNContactFormatter.string(from: contact, style: .fullName) ?? "알 수 없음"
    }

    // 전화번호 포맷
    func formatPhoneNumber(_ phoneNumber: CNPhoneNumber) -> String {
        let formatter = CNPhoneNumberFormatter()
        return formatter.string(from: phoneNumber)
    }

    // 주소 포맷
    func formatPostalAddress(_ address: CNPostalAddress) -> String {
        let formatter = CNPostalAddressFormatter()
        return formatter.string(from: address)
    }

    // 연락처 레이블 현지화
    func localizedLabel(for label: String) -> String {
        return CNLabeledValue<NSString>.localizedString(forLabel: label)
    }
}

📱 Complete Example — Contact Management App

ContactsAppView.swift — Contact Management App

import SwiftUI
import Contacts

struct ContactsAppView: View {
    @State private var manager = ContactsManager()
    @State private var contacts: [CNContact] = []
    @State private var searchText = ""
    @State private var showingAddContact = false
    @State private var errorMessage: String?

    var filteredContacts: [CNContact] {
        if searchText.isEmpty {
            return contacts
        } else {
            return contacts.filter { contact in
                let fullName = CNContactFormatter.string(from: contact, style: .fullName) ?? ""
                return fullName.localizedCaseInsensitiveContains(searchText)
            }
        }
    }

    var body: some View {
        NavigationStack {
            List {
                ForEach(filteredContacts, id: \.identifier) { contact in
                    NavigationLink {
                        ContactDetailView(contact: contact, manager: manager)
                    } label: {
                        ContactRow(contact: contact)
                    }
                }
                .onDelete(perform: deleteContacts)
            }
            .navigationTitle("연락처")
            .searchable(text: $searchText, prompt: "연락처 검색")
            .toolbar {
                Button {
                    showingAddContact = true
                } label: {
                    Image(systemName: "plus")
                }
            }
            .sheet(isPresented: $showingAddContact) {
                AddContactView(manager: manager) {
                    Task {
                        await loadContacts()
                    }
                }
            }
            .alert("오류", isPresented: .constant(errorMessage != nil)) {
                Button("확인") {
                    errorMessage = nil
                }
            } message: {
                Text(errorMessage ?? "")
            }
            .task {
                await loadContacts()
            }
        }
    }

    func loadContacts() async {
        let authorized = await manager.ensureAuthorization()

        guard authorized else {
            errorMessage = "연락처 접근 권한이 필요합니다"
            return
        }

        do {
            let fetchedContacts = try manager.fetchAllContacts()
            await MainActor.run {
                contacts = fetchedContacts.sorted { c1, c2 in
                    let name1 = CNContactFormatter.string(from: c1, style: .fullName) ?? ""
                    let name2 = CNContactFormatter.string(from: c2, style: .fullName) ?? ""
                    return name1 < name2
                }
            }
        } catch {
            errorMessage = "연락처를 불러올 수 없습니다"
        }
    }

    func deleteContacts(at offsets: IndexSet) {
        for index in offsets {
            let contact = filteredContacts[index]
            do {
                try manager.deleteContact(identifier: contact.identifier)
            } catch {
                errorMessage = "연락처 삭제 실패"
            }
        }

        Task {
            await loadContacts()
        }
    }
}

struct ContactRow: View {
    let contact: CNContact

    var body: some View {
        HStack {
            if let imageData = contact.imageData,
               let uiImage = UIImage(data: imageData) {
                Image(uiImage: uiImage)
                    .resizable()
                    .scaledToFill()
                    .frame(width: 40, height: 40)
                    .clipShape(Circle())
            } else {
                Image(systemName: "person.circle.fill")
                    .resizable()
                    .frame(width: 40, height: 40)
                    .foregroundStyle(.gray)
            }

            VStack(alignment: .leading) {
                Text(CNContactFormatter.string(from: contact, style: .fullName) ?? "알 수 없음")
                    .font(.headline)

                if let phoneNumber = contact.phoneNumbers.first?.value.stringValue {
                    Text(phoneNumber)
                        .font(.subheadline)
                        .foregroundStyle(.secondary)
                }
            }
        }
    }
}

struct ContactDetailView: View {
    let contact: CNContact
    let manager: ContactsManager

    var body: some View {
        List {
            Section("전화번호") {
                ForEach(contact.phoneNumbers, id: \.identifier) { labeledValue in
                    HStack {
                        Text(CNLabeledValue<NSString>.localizedString(forLabel: labeledValue.label ?? ""))
                            .foregroundStyle(.secondary)
                        Spacer()
                        Text(labeledValue.value.stringValue)
                    }
                }
            }

            Section("이메일") {
                ForEach(contact.emailAddresses, id: \.identifier) { labeledValue in
                    HStack {
                        Text(CNLabeledValue<NSString>.localizedString(forLabel: labeledValue.label ?? ""))
                            .foregroundStyle(.secondary)
                        Spacer()
                        Text(labeledValue.value as String)
                    }
                }
            }
        }
        .navigationTitle(CNContactFormatter.string(from: contact, style: .fullName) ?? "연락처")
    }
}

struct AddContactView: View {
    let manager: ContactsManager
    let onSave: () -> Void

    @State private var givenName = ""
    @State private var familyName = ""
    @State private var phoneNumber = ""
    @Environment(\.dismiss) var dismiss

    var body: some View {
        NavigationStack {
            Form {
                TextField("이름", text: $givenName)
                TextField("성", text: $familyName)
                TextField("전화번호", text: $phoneNumber)
                    .keyboardType(.phonePad)
            }
            .navigationTitle("새 연락처")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .cancellationAction) {
                    Button("취소") {
                        dismiss()
                    }
                }

                ToolbarItem(placement: .confirmationAction) {
                    Button("저장") {
                        saveContact()
                    }
                    .disabled(givenName.isEmpty || familyName.isEmpty)
                }
            }
        }
    }

    func saveContact() {
        do {
            try manager.createContact(
                givenName: givenName,
                familyName: familyName,
                phoneNumbers: phoneNumber.isEmpty ? [] : [phoneNumber]
            )
            onSave()
            dismiss()
        } catch {
            print("연락처 저장 실패: \(error)")
        }
    }
}

💡 HIG Guidelines

Permission Request: 연락처 접근이 필요한 이유를 명확히 설명
최소 권한: 필요한 최소한의 연락처 정보만 요청
연락처 선택기 사용: Use the system contact picker (CNContactPickerViewController) when possible.
개인정보 보호: Require user consent before sending contact data to a server
Error Handling: Provide guidance to navigate to Settings when permission is denied

🎯 Practical Usage

소셜 앱: 친구 초대, 연락처 동기화
Messaging Apps: 빠른 연락처 검색 및 메시지 발송
이메일 클라이언트: 받는 사람 자동 완성
Event Apps: 참석자 추가, 초대장 발송
비즈니스 앱: CRM, 고객 관리, 명함 관리

📚 Learn More

⚡️ Performance Tips: 연락처 조회 시 필요한 키만 keysToFetch. Fetching all keys may degrade performance. Request image data only when needed.

📎 Apple Official Resources

📘 Documentation 🎬 WWDC Sessions