Kontaktauswahl

Die Android-Kontaktauswahl ist eine standardisierte, durchsuchbare Oberfläche, über die Nutzer Kontakte für Ihre App freigeben können. Sie ist auf Geräten mit Android 17 (API‑Level 37) oder höher verfügbar und bietet eine datenschutzfreundliche Alternative zur umfassenden Berechtigung READ_CONTACTS. Anstatt Zugriff auf das gesamte Adressbuch des Nutzers anzufordern, gibt Ihre App die benötigten Datenfelder an, z. B. Telefonnummern oder E-Mail-Adressen, und der Nutzer wählt bestimmte Kontakte aus, die freigegeben werden sollen. Dadurch erhält Ihre App nur Lesezugriff auf die ausgewählten Daten. So haben Sie eine detaillierte Kontrolle und können gleichzeitig eine einheitliche Nutzererfahrung mit integrierter Suche, Profilwechsel und Mehrfachauswahl bieten, ohne die Benutzeroberfläche selbst entwickeln oder verwalten zu müssen.

Kontaktauswahl einbinden

Verwenden Sie den Intent ContactsPickerSessionContract.ACTION_PICK_CONTACTS, um die Kontaktauswahl zu integrieren. Mit diesem Intent wird die Auswahl gestartet und die ausgewählten Kontakte werden an Ihre App zurückgegeben.

Im Gegensatz zum alten ACTION_PICK können Sie mit der Kontaktauswahl mehrere Datenfelder gleichzeitig angeben, die Ihre App benötigt. Dazu verwenden Sie ContactsPickerSessionContract.EXTRA_REQUESTED_DATA_FIELDS und übergeben ein ArrayList<String> von MIME-Typen, die in ContactsContract.CommonDataKinds definiert sind.

Häufige MIME-Typen sind:

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

Auswahl starten

Verwenden Sie registerForActivityResult mit dem StartActivityForResult-Vertrag, um die Auswahl zu starten. Sie können den Intent so konfigurieren, dass einzelne oder mehrere Auswahlen möglich sind.

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

Auswahlmodus

Die Benutzeroberfläche der Kontaktauswahl wird an die angeforderten Datenfelder angepasst. Je nach diesen Anforderungen können Nutzer entweder einen gesamten Kontaktdatensatz auswählen, wenn mehrere Felder benötigt werden, oder bestimmte Datenelemente aus den Informationen eines Kontakts.

Die verschiedenen UI-Modi der Kontaktauswahl
Abbildung 1. Die Benutzeroberfläche der Kontaktauswahl wird an die angeforderten Datenfelder angepasst (Auswahl eines einzelnen Kontakts, mehrerer Kontakte und mehrerer Telefonnummern).

Einzelnen Kontakt auswählen

In diesem Beispiel fordert die App nur Telefonnummern an. Die Auswahl wird gefiltert, sodass nur Kontakte mit Telefonnummern angezeigt werden. Der Nutzer kann dann eine bestimmte Nummer auswählen.

// 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 {
    putExtra(EXTRA_USE_SYSTEM_CONTACTS_PICKER, true)
    putStringArrayListExtra(
        EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
        requestedFields
    )
}

// Launch the picker
pickContact.launch(pickContactIntent)

Mehrere Kontakte auswählen

Wenn Sie die Mehrfachauswahl aktivieren möchten, fügen Sie das Intent.EXTRA_ALLOW_MULTIPLE-Extra hinzu. Optional können Sie die Anzahl der Elemente begrenzen, die ein Nutzer auswählen kann.

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 {
    putExtra(EXTRA_USE_SYSTEM_CONTACTS_PICKER, true)
    // 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)

Ergebnisse verarbeiten

Wenn der Nutzer die Auswahl abgeschlossen hat, gibt das System eine RESULT_OK und eine Sitzungs-URI zurück. Dieser URI gewährt temporären Lesezugriff auf die ausgewählten Daten.

Sie können diesen URI mit einem Standard-ContentResolver abfragen. Der resultierende Cursor enthält die angeforderten Datenfelder und entspricht dem Schema von 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()
}

Abwärtskompatibilität

Bei Apps, die auf Android 17 (API‑Level 37) und höher ausgerichtet sind, wird der vorhandene Intent.ACTION_PICK-Intent automatisch aktualisiert, um die neue Kontaktauswahl-Oberfläche zu verwenden.

Wenn Ihre App bereits ACTION_PICK verwendet, müssen Sie Ihren Code nicht ändern, um die neue Benutzeroberfläche zu erhalten. Wenn Sie jedoch neue Funktionen wie den Empfang eines einzelnen Uri zum Abfragen von Kontaktdaten, das Umschalten zwischen privaten und Arbeitsprofilen oder mehrere Datenfeldanfragen nutzen möchten, müssen Sie Ihre Implementierung aktualisieren, damit ContactsPickerSessionContract.ACTION_PICK_CONTACTS oder die neuen Intent-Extras verwendet werden.

Tests mit älteren SDK-Zielversionen

Sie können das neue Auswahltoolverhalten auf Geräten mit Android 17 und höher testen, auch wenn Ihre App auf eine niedrigere SDK-Version ausgerichtet ist. Fügen Sie dazu dem ACTION_PICK-Intent das boolesche Extra EXTRA_USE_SYSTEM_CONTACTS_PICKER hinzu.

Best Practices

  • Nur das anfordern, was Sie benötigen: Wenn Ihre App nur eine SMS senden muss, fordern Sie Phone.CONTENT_ITEM_TYPE an. Die Auswahl wird automatisch nach Kontakten ohne Telefonnummer gefiltert, was zu einer übersichtlicheren Benutzeroberfläche für den Nutzer führt.
  • Mehrere Dateneinträge pro Kontakt verwalten: Einzelne Kontakte enthalten oft verschiedene E‑Mail-Adressen oder Telefonnummern. Damit diese klar und intuitiv für den Nutzer dargestellt werden, empfiehlt es sich, sie mit ContactsContract.Contacts.LOOKUP_KEY zu gruppieren. Außerdem können Sie für jeden Eintrag bestimmte Labels abrufen, z. B. „Arbeit“ oder „Privat“, um in der Benutzeroberfläche Ihrer App detailliertere Auswahlmöglichkeiten anzubieten.
  • Daten sofort speichern: Der Sitzungs-URI gewährt eine temporäre Leseberechtigung. Wenn Sie später (nachdem der App-Prozess beendet wurde) auf diese Kontaktdaten zugreifen müssen, muss Ihre App die Kontaktdaten speichern.
  • Nicht auf Kontodaten verlassen: Zum Schutz der Privatsphäre der Nutzer und zur Vermeidung von Fingerprinting werden kontospezifische Metadaten aus den Ergebnissen entfernt.