Kişi seçici

Android Kişi Seçici, kullanıcıların kişilerle ilgili bilgileri uygulamanızla paylaşması için standartlaştırılmış ve göz atılabilir bir arayüzdür. Android 17 veya sonraki sürümlerin yüklü olduğu cihazlarda kullanılabilen seçici, geniş kapsamlı READ_CONTACTS iznine gizliliği koruyan bir alternatif sunar. Uygulamanız, kullanıcının tüm adres defterine erişim isteğinde bulunmak yerine ihtiyaç duyduğu veri alanlarını (ör. telefon numaraları veya e-posta adresleri) belirtir ve kullanıcı, paylaşılacak belirli kişileri seçer. Bu sayede uygulamanız yalnızca seçilen verilere okuma erişimi kazanır. Böylece, kullanıcı arayüzünü oluşturmak veya bakımını yapmak zorunda kalmadan yerleşik arama, profil değiştirme ve çoklu seçim özellikleriyle tutarlı bir kullanıcı deneyimi sunarken ayrıntılı kontrol de sağlanır.

Kişi seçiciyi entegre etme

Kişi seçiciyi entegre etmek için Intent.ACTION_PICK_CONTACTS amacını kullanın. Bu amaç, seçiciyi başlatır ve seçilen kişileri uygulamanıza döndürür.

Eski ACTION_PICK'dan farklı olarak, Kişi Seçici, uygulamanızın gerektirdiği birden fazla veri alanını aynı anda belirtmenize olanak tanır. Bunu, Intent.EXTRA_REQUESTED_DATA_FIELDS kullanarak yaparsınız. ContactsContract.CommonDataKinds içinde tanımlanan MIME türlerinin ArrayList<String>'sini iletirsiniz.

Yaygın MIME türleri şunlardır:

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

Seçiciyi başlatma

Seçiciyi başlatmak için registerForActivityResult tuşunu StartActivityForResult sözleşmesiyle birlikte kullanın. Amacı, tek veya birden çok seçim yapmaya izin verecek şekilde yapılandırabilirsiniz.

Tek bir kişi seçme

Bu örnekte uygulama yalnızca telefon numarası istiyor. Seçici, listeyi yalnızca telefon numarası olan kişileri gösterecek şekilde filtreler ve kullanıcının belirli bir numarayı seçmesine olanak tanır.

Kotlin

// Define the specific data fields you need
val requestedFields = arrayListOf(
    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
)

// Set up the intent
val pickContactIntent = Intent(Intent.ACTION_PICK_CONTACTS).apply {
    type = ContactsContract.Contacts.CONTENT_TYPE
    putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS, requestedFields)
}

// Launch the picker
pickContactLauncher.launch(pickContactIntent)

Java

// Define the specific data fields you need
ArrayList<String> requestedFields = new ArrayList<>();
requestedFields.add(ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE);

// Set up the intent
Intent pickContactIntent = new Intent(Intent.ACTION_PICK_CONTACTS);
pickContactIntent.setType(ContactsContract.Contacts.CONTENT_TYPE);
pickContactIntent.putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS,
        requestedFields);

// Launch the picker
pickContactLauncher.launch(pickContactIntent);

Birden fazla kişi seçme

Çoklu seçimi etkinleştirmek için Intent.EXTRA_ALLOW_MULTIPLE ekleyin. İsteğe bağlı olarak, kullanıcının seçebileceği öğe sayısını sınırlayabilirsiniz.

Kotlin

val requestedFields = arrayListOf(
    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE,
    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
)

val pickMultipleIntent = Intent(Intent.ACTION_PICK_CONTACTS).apply {
    type = ContactsContract.Contacts.CONTENT_TYPE
    putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS, requestedFields)
    // Enable multi-select
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
    // Optional: Set a custom limit (max 50 recommended)
    putExtra(Intent.EXTRA_SELECTION_LIMIT, 10)
}

pickMultipleLauncher.launch(pickMultipleIntent)

Sonuçları işleme

Kullanıcı seçimi tamamladığında sistem RESULT_OK ve oturum URI'si döndürür. Bu URI, seçilen verilere geçici okuma erişimi verir.

Bu URI'yi standart bir ContentResolver kullanarak sorgulayabilirsiniz. Sonuçta elde edilen Cursor, istenen veri alanlarını içerir ve ContactsContract.Data şemasını takip eder.

Kotlin

private val pickContactLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // The result data contains the Session URI
        val sessionUri = result.data?.data
        sessionUri?.let { uri ->
            processSelectedContacts(uri)
        }
    } else {
        // User cancelled the picker
    }
}

private fun processSelectedContacts(sessionUri: Uri) {
    // Define the projection (columns) you want to retrieve
    val projection = arrayOf(
        ContactsContract.Data.CONTACT_ID,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY,
        ContactsContract.Data.MIMETYPE,
        ContactsContract.Data.DATA1 // Generic data column (Phone number, Email, etc.)
    )

    contentResolver.query(sessionUri, projection, null, null, null)?.use { cursor ->
        val mimeTypeIdx = cursor.getColumnIndex(ContactsContract.Data.MIMETYPE)
        val dataIdx = cursor.getColumnIndex(ContactsContract.Data.DATA1)
        val nameIdx = cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY)

        while (cursor.moveToNext()) {
            val mimeType = cursor.getString(mimeTypeIdx)
            val dataValue = cursor.getString(dataIdx)
            val name = cursor.getString(nameIdx)

            when (mimeType) {
                ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE -> {
                    Log.d("ContactPicker", "Picked Phone: $dataValue for $name")
                }
                ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE -> {
                    Log.d("ContactPicker", "Picked Email: $dataValue for $name")
                }
            }
        }
    }
}

Geriye Dönük Uyumluluk

Android 17 ve sonraki sürümleri hedefleyen uygulamalarda sistem, yeni Kişi Seçici arayüzünü kullanmak için mevcut Intent.ACTION_PICK amacını otomatik olarak yükseltir.

Uygulamanızda zaten ACTION_PICK kullanılıyorsa yeni kullanıcı arayüzünü almak için kodunuzu değiştirmeniz gerekmez. Ancak, iletişim verilerini sorgulamak için tek bir Uri alma, kişisel ve iş profilleri arasında geçiş yapma veya birden fazla veri alanı isteği gibi yeni özelliklerden yararlanmak için uygulamanızı Intent.ACTION_PICK_CONTACTS veya yeni amaç ekstralarını kullanacak şekilde güncellemeniz gerekir.

Eski SDK'larda test etme

Uygulamanız daha düşük bir SDK sürümünü hedeflese bile EXTRA_USE_SYSTEM_CONTACTS_PICKER boolean ekstrasını ACTION_PICK amacınıza ekleyerek Android 17 ve sonraki sürümlerin yüklü olduğu cihazlarda yeni seçici davranışını test edebilirsiniz.

En iyi uygulamalar

• Yalnızca ihtiyacınız olanı isteyin: Uygulamanızın yalnızca SMS göndermesi gerekiyorsa Phone.CONTENT_ITEM_TYPE iznini isteyin. Seçici, telefon numarası olmayan kişileri otomatik olarak filtreleyerek kullanıcı için daha temiz bir kullanıcı arayüzü sağlar.
• Verileri hemen kalıcı hale getirme: Oturum URI'si geçici okuma izni verir. Bu iletişim bilgilerine daha sonra (uygulama işleminiz sonlandırıldıktan sonra) erişmeniz gerekirse uygulamanızın iletişim verilerini kalıcı olarak saklaması gerekir.
• Hesap verilerine güvenmeyin: Kullanıcı gizliliğini korumak ve parmak izi oluşturmayı önlemek için sonuçlardan hesaba özel meta veriler kaldırılır.