연락처 선택도구

Android 연락처 선택 도구는 사용자가 앱과 연락처를 공유할 수 있는 표준화된 탐색 가능한 인터페이스입니다. Android 17 (API 수준 37) 이상을 실행하는 기기에서 사용할 수 있는 선택 도구는 광범위한 READ_CONTACTS 권한을 대체하는 개인 정보 보호 대안을 제공합니다. 사용자의 전체 주소록에 대한 액세스를 요청하는 대신 앱은 전화번호나 이메일 주소와 같이 필요한 데이터 필드를 지정하고 사용자는 공유할 특정 연락처를 선택합니다. 이렇게 하면 앱에 선택한 데이터에 대한 읽기 액세스 권한만 부여되므로 UI를 빌드하거나 유지관리하지 않고도 내장 검색, 프로필 전환, 다중 선택 기능을 통해 일관된 사용자 환경을 제공하면서 세부적인 제어가 가능합니다.

연락처 선택 도구 통합

연락처 선택기를 통합하려면 Intent.ACTION_PICK_CONTACTS 인텐트를 사용하세요. 이 인텐트는 선택기를 실행하고 선택한 연락처를 앱에 반환합니다.

기존 ACTION_PICK와 달리 연락처 선택기를 사용하면 앱에 필요한 여러 데이터 필드를 동시에 지정할 수 있습니다. ContactsContract.CommonDataKinds에 정의된 MIME 유형의 ArrayList<String>을 전달하여 Intent.EXTRA_REQUESTED_DATA_FIELDS을 사용합니다.

일반적인 MIME 유형은 다음과 같습니다.

  • ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
  • ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
  • ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE

선택기 실행

StartActivityForResult 계약과 함께 registerForActivityResult를 사용하여 선택기를 실행합니다. 단일 또는 다중 선택을 허용하도록 인텐트를 구성할 수 있습니다.

// Launcher for the Contact Picker intent
val pickContact = rememberLauncherForActivityResult(StartActivityForResult()) {
    if (it.resultCode == Activity.RESULT_OK) {
        val resultUri = it.data?.data ?: return@rememberLauncherForActivityResult

        // Process the result URI in a background thread to fetch all selected contacts
        coroutine.launch {
            contacts = processContactPickerResultUri(resultUri, context)
        }
    }
}

선택 모드

연락처 선택기의 UI는 요청된 데이터 필드에 따라 조정됩니다. 이러한 요구사항에 따라 사용자는 여러 필드가 필요한 경우 전체 연락처 레코드를 선택하거나 연락처 정보 내에서 특정 데이터 항목을 선택할 수 있습니다.

연락처 선택 도구의 다양한 UI 모드
그림 1. 연락처 선택 도구 인터페이스는 요청된 데이터 필드 (단일 연락처, 여러 연락처, 여러 전화번호 선택)에 맞게 조정됩니다.

단일 연락처 선택

이 예시에서 앱은 전화번호만 요청합니다. 선택기는 목록을 필터링하여 전화번호가 있는 연락처만 표시하고 사용자가 특정 번호를 선택할 수 있도록 합니다.

// Define the specific contact data fields you need
val requestedFields = arrayListOf(
    Email.CONTENT_ITEM_TYPE,
    Phone.CONTENT_ITEM_TYPE,
)

// Set up the intent for the Contact Picker
val pickContactIntent = Intent(ACTION_PICK_CONTACTS).apply {
    putStringArrayListExtra(
        EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
        requestedFields
    )
}

// Launch the picker
pickContact.launch(pickContactIntent)

여러 연락처 선택

다중 선택을 사용 설정하려면 Intent.EXTRA_ALLOW_MULTIPLE extra를 추가합니다. 사용자가 선택할 수 있는 항목 수를 선택적으로 제한할 수 있습니다.

val requestedFields = arrayListOf(
    Email.CONTENT_ITEM_TYPE,
    Phone.CONTENT_ITEM_TYPE,
)

// Set up the intent for the Contact Picker
val pickContactIntent = Intent(ACTION_PICK_CONTACTS).apply {
    // Enable multi-select
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
    // Set limit of selectable contacts
    putExtra(EXTRA_PICK_CONTACTS_SELECTION_LIMIT, 5)
    // Define the specific contact data fields you need
    putStringArrayListExtra(
        EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
        requestedFields
    )
    // Enable this option to only filter contacts that have all the requested data fields
    putExtra(EXTRA_PICK_CONTACTS_MATCH_ALL_DATA_FIELDS, false)
}

// Launch the picker
pickContact.launch(pickContactIntent)

결과 처리

사용자가 선택을 완료하면 시스템에서 RESULT_OK 및 세션 URI를 반환합니다. 이 URI는 선택한 데이터에 대한 임시 읽기 액세스 권한을 부여합니다.

표준 ContentResolver를 사용하여 이 URI를 쿼리할 수 있습니다. 결과 Cursor에는 요청된 데이터 필드가 포함되어 있으며 ContactsContract.Data의 스키마를 따릅니다.

// Data class representing a parsed Contact with selected details.
data class Contact(
    val lookupKey: String,
    val name: String,
    val emails: List<String>,
    val phones: List<String>
)

// Helper function to query the content resolver with the URI returned by the Contact Picker.
// Parses the cursor to extract contact details such as name, email, and phone number.
private suspend fun processContactPickerResultUri(
    sessionUri: Uri,
    context: Context
): List<Contact> = withContext(Dispatchers.IO) {
    // Define the columns we want to retrieve from the ContactPicker ContentProvider
    val projection = arrayOf(
        ContactsContract.Contacts.LOOKUP_KEY,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY,
        ContactsContract.Data.MIMETYPE, // Type of data (e.g., email or phone)
        ContactsContract.Data.DATA1, // The actual data (Phone number / Email string)
    )

    // We use `LOOKUP_KEY` as a unique ID to aggregate all contact info related to a same person
    val contactsMap = mutableMapOf<String, Contact>()

    // Note: The Contact Picker Session Uri doesn't support custom selection & selectionArgs.
    // We query the URI directly to get the results chosen by the user.
    context.contentResolver.query(sessionUri, projection, null, null, null)?.use { cursor ->
        // Get the column indices for our requested projection
        val lookupKeyIdx = cursor.getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY)
        val mimeTypeIdx = cursor.getColumnIndex(ContactsContract.Data.MIMETYPE)
        val nameIdx = cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY)
        val data1Idx = cursor.getColumnIndex(ContactsContract.Data.DATA1)

        while (cursor.moveToNext()) {
            val lookupKey = cursor.getString(lookupKeyIdx)
            val mimeType = cursor.getString(mimeTypeIdx)
            val name = cursor.getString(nameIdx) ?: ""
            val data1 = cursor.getString(data1Idx) ?: ""

            val email = if (mimeType == Email.CONTENT_ITEM_TYPE) data1 else null
            val phone = if (mimeType == Phone.CONTENT_ITEM_TYPE) data1 else null

            val existingContact = contactsMap[lookupKey]
            if (existingContact != null) {
                contactsMap[lookupKey] = existingContact.copy(
                    emails = if (email != null) existingContact.emails + email else existingContact.emails,
                    phones = if (phone != null) existingContact.phones + phone else existingContact.phones
                )
            } else {
                contactsMap[lookupKey] = Contact(
                    lookupKey = lookupKey,
                    name = name,
                    emails = if (email != null) listOf(email) else emptyList(),
                    phones = if (phone != null) listOf(phone) else emptyList()
                )
            }
        }
    }

    return@withContext contactsMap.values.toList()
}

이전 버전과의 호환성

Android 17 (API 수준 37) 이상을 타겟팅하는 앱의 경우 시스템에서 새 연락처 선택기 인터페이스를 사용하도록 기존 Intent.ACTION_PICK 인텐트를 자동으로 업그레이드합니다.

앱에서 이미 ACTION_PICK를 사용하고 있다면 새 UI를 수신하기 위해 코드를 변경할 필요가 없습니다. 하지만 연락처 데이터를 쿼리하는 단일 Uri 수신, 개인 및 직장 프로필 간 전환, 여러 데이터 필드 요청과 같은 새로운 기능을 활용하려면 Intent.ACTION_PICK_CONTACTS 또는 새로운 인텐트 추가 기능을 사용하도록 구현을 업데이트해야 합니다.

이전 대상 SDK에서 테스트

ACTION_PICK 인텐트에 EXTRA_USE_SYSTEM_CONTACTS_PICKER 불리언 추가 항목을 추가하면 앱이 낮은 SDK 버전을 타겟팅하더라도 Android 17 이상을 실행하는 기기에서 새로운 선택기 동작을 테스트할 수 있습니다.

권장사항

  • 필요한 것만 요청: 앱에서 SMS만 보내야 하는 경우 Phone.CONTENT_ITEM_TYPE를 요청합니다. 선택기는 전화번호가 없는 연락처를 자동으로 필터링하므로 사용자에게 더 깔끔한 UI가 표시됩니다.
  • 연락처당 여러 데이터 항목 관리: 개별 연락처에는 다양한 이메일 주소나 전화번호가 포함되는 경우가 많습니다. 사용자에게 명확하고 직관적으로 표시되도록 하려면 ContactsContract.Contacts.LOOKUP_KEY를 사용하여 그룹화하는 것이 좋습니다. 또한 각 항목 (예: 직장 또는 개인)의 특정 라벨을 검색하여 앱 인터페이스 내에서 더 세분화된 선택 옵션을 제공할 수 있습니다.
  • 데이터를 즉시 유지: 세션 URI는 임시 읽기 권한을 부여합니다. 나중에 (앱 프로세스가 종료된 후) 이 연락처 정보에 액세스해야 하는 경우 앱은 연락처 데이터를 유지해야 합니다.
  • 계정 데이터를 사용하지 않음: 사용자 개인 정보를 보호하고 지문 생성을 방지하기 위해 계정별 메타데이터가 결과에서 삭제됩니다.