Android'de kişi eklemenin ve düzenlemenin daha güvenilir bir yolu

Neler değişecek?

Yakında çıkacak Android sürümünü hedefleyen uygulamalar, WRITE_CONTACTS izniyle kişilere doğrudan yazamayacak. Bunun yerine standart kişi intent'lerini (ACTION_INSERT, ACTION_EDIT ve ACTION_INSERT_OR_EDIT) kullanabilirsiniz. Tam bir referans uygulama için intent'leri kullanarak kişileri değiştirme ile ilgili geliştirici kılavuzuna bakın. 

Yakında çıkacak Android sürümünü çalıştıran cihazlarda bu üç kişi amacı tutarlı bir şekilde davranır ve hiçbir izin gerektirmez. Uygulamanız, yakında çıkacak Android sürümünü veya sonraki sürümleri hedefliyorsa ve doğrudan kişilere yazmaya çalışırsa bu yazma işlemleri reddedilir ve SecurityException ya da izin reddiyle sonuçlanır. Kişi oluşturmak ve değiştirmek için geniş erişim gerektiren az sayıdaki uygulama için Android 17 QPR2'de (2026'nın 4. çeyreği) yeni bir özel uygulama erişim izni (MANAGE_CONTACTS) kullanıma sunulacak. Google Play, bugün MANAGE_CONTACTS dahil olmak üzere kişilere erişimle ilgili güncellenmiş yönergeleri yayınlıyor.

Bu değişikliği neden yapıyoruz?

Şu anda uygulamanızın tek bir kişiyi bile kaydetmesi gerekiyorsa WRITE_CONTACTS iznini istiyor olabilirsiniz. Ancak bu izin, geniş kapsamlı erişim sağlayarak bir uygulamanın, kullanıcı etkileşimi olmadan bile arka planda cihazdaki kişilerde kapsamlı değişiklikler yapmasına olanak tanır. Çoğu uygulamanın bu kadar geniş bir izne ihtiyacı yoktur.

Alternatifler olsa da sizden aldığımız geri bildirimler, bu alternatiflerin ekosistem genelinde daha standart hale getirilmesi gerektiğini gösteriyor. Daha önce, kişi amaçları cihazdan cihaza farklı şekilde davranıyordu. Bazı düzenleyiciler, ilettiğiniz verileri (ör. kişi fotoğrafı) sildi. Bazı cihazlarda geri düğmesi, kullanıcının niyeti olmadan kişiyi kaydetti veya "yeni kişi oluştur" seçeneğini bulmak zordu. Bu nedenle izin istemek mantıklı bir seçimdi. Yakında çıkacak Android sürümünde tüm bu sorunları düzeltiyoruz ve bu sürümü çalıştıran cihazların aynı standartlara uymasını zorunlu kılıyoruz.

Bunun yerine ne kullanılmalı?

Kişi ekleme veya düzenleme: Kişi intent'lerini kullanma

ACTION_INSERT, ACTION_EDIT ve ACTION_INSERT_OR_EDIT intent'lerini kullandığınızda sistem, temiz ve standartlaştırılmış bir kişi düzenleyici deneyimi sunarak zorlu işleri halleder. Yeni girişler için hızlı bir yarım sayfa form açar veya kullanıcının mevcut bir kişiyi kolayca arayıp bilgi eklemesine olanak tanır. Kullanıcılar, uygulamanızın doğrudan yazma iznine ihtiyaç duymadan daha fazla ayrıntı girmek için bu düzenleyiciyi tam sayfa düzenleyiciye sorunsuz bir şekilde genişletebilir. Aşağıdaki geçici UX maketlerini inceleyin: 

Şekil 1: Yeni Kişi Oluşturma  *Kullanıcı deneyimi nihai değildir*

Şekil 2: Mevcut bir kişiye bilgi ekleme *UX nihai değildir*

Not: Farklı cihaz üreticileri, kullanıcı deneyimini kendi işletim sistemi stillerine uyacak şekilde değiştirebilir ancak davranış tutarlı kalır.

Intent'inizle birlikte Ekstralar olarak bilinen isteğe bağlı veri yüklerini ileterek oluşturma sürecini daha da kolaylaştırabilirsiniz:

• EXTRA_ACCOUNT, kişinin hangi hesaba kaydedileceğini önerir. Bu, uygulamanız kişileri senkronize ediyorsa faydalı olur. Bu ek özellik daha önce de vardı ancak desteklenen cihazlar farklılık gösteriyordu. Yakında çıkacak Android sürümünden itibaren destek, cihazlar genelinde standartlaştırılacak.
• EXTRA_PHOTO_URI, kişi resmini önceden doldurmak için bir fotoğraf gönderir. Düzenleyici, URI okuma iznini sizin için yönetir. Bu, yakında çıkacak Android sürümüyle birlikte sunulan yeni bir özelliktir ve ekosistem genelinde desteklenecektir.

// Requires android.permission.WRITE_CONTACTS
fun saveContactDirectly(context: Context, name: String, phone: String, account: Account) {
    val ops = arrayListOf(
        ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
            .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, account.type)
            .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, account.name)
            .build(),
        ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(
                ContactsContract.Data.MIMETYPE,
                ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
            )
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name)
            .build(),
        ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(
                ContactsContract.Data.MIMETYPE,
                ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
            )
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .build()
    )
    context.contentResolver.applyBatch(ContactsContract.AUTHORITY, ops)
}

fun saveContactWithEditor(
    context: Context,
    name: String,
    phone: String,
    account: Account,
    photoUri: Uri
) {
    val intent = Intent(Intent.ACTION_INSERT, ContactsContract.Contacts.CONTENT_URI).apply {
        putExtra(ContactsContract.Intents.Insert.NAME, name)
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
        // Suggest which account the contact is saved to
        putExtra(ContactsContract.Intents.Insert.EXTRA_ACCOUNT, account)
        // New in the upcoming Android release: pre-fill the contact photo
        putExtra(ContactsContract.Intents.Insert.EXTRA_PHOTO_URI, photoUri)
        clipData = ClipData.newRawUri("", photoUri)
        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
    }
    context.startActivity(intent)
}

// Requires android.permission.WRITE_CONTACTS
fun addPhoneDirectly(context: Context, rawContactId: Long, phone: String) {
    val values = ContentValues().apply {
        put(ContactsContract.Data.RAW_CONTACT_ID, rawContactId)
        put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)
        put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
    }
    context.contentResolver.insert(ContactsContract.Data.CONTENT_URI, values)
}

fun addPhoneWithEditor(context: Context, phone: String) {
    val intent = Intent(Intent.ACTION_INSERT_OR_EDIT).apply {
        type = ContactsContract.Contacts.CONTENT_ITEM_TYPE
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
    }
    context.startActivity(intent)
}

fun editKnownContact(context: Context, contactUri: Uri, phone: String) {
    val intent = Intent(Intent.ACTION_EDIT, contactUri).apply {
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
    }
    context.startActivity(intent)
}

Kişi seçme: Kişi Seçici'yi kullanma

Yalnızca kullanıcının seçtiği kişileri okumanız gerekiyorsa Android 17'den itibaren kullanılabilen Kişi Seçici'yi kullanın. İzin gerekmez.

Arama ve mesajlaşma uygulamaları: Kişi Dizini'ni kullanma

Bazı uygulamalar, kişilere "Şununla ara..." veya "Şununla mesaj gönder..." işlemlerini ekler. Böylece kullanıcılar Telefon veya Kişiler uygulamasından arama ya da sohbet başlatabilir. Uygulamanız şu anda kullanıcının kişilerine ek girişler yazarak bunu yapıyorsa Android QPR2'de (2026'nın 4. çeyreği) kullanıma sunulacak olan Kişiler Dizini'ne geçin. Uygulamanızın, kullanıcıların birbirleriyle nasıl iletişim kurabileceğini yayınladığı yeni bir sistem dizinidir. Bu dizin, kullanıcının kişilerini düzenlemez.

Uygulamaların nasıl taşınabileceğine dair örnekler

Bu alternatiflerin uygulamada nasıl çalıştığını görmek için farklı uygulama türlerinin kişi erişimine nasıl yaklaşabileceğine dair birkaç örneği aşağıda bulabilirsiniz:

Kontrol edilecek değişiklikler

• Özel veri türleri düzenleyicide desteklenmez. Standart ContactsContract.CommonDataKinds türleri dışındaki MIME türlerine sahip Insert.DATA satırları iletirseniz bu MIME türleri, düzenleyici tarafından sessizce yoksayılır.
• SHOW_OR_CREATE_CONTACT , sistem düzenleyicisi tarafından işlenmiyor. Cihazla birlikte gelen Kişiler uygulamaları bu işlemi gerçekleştirmeye devam edebilir. Cihazlar arasında tutarlı bir davranış için ACTION_INSERT_OR_EDIT kullanın.
• Yazma işlemleri varsayılan olarak başarısız olur. Yaklaşan Android sürümünü hedeflediğinizde, MANAGE_CONTACTS olmadan yapılan tüm doğrudan yazma işlemleri SecurityException or permission denial ile sonuçlanır. Test edin.

MANAGE_CONTACTS'a ihtiyacım var mı?

Muhtemelen karşılaşmazsınız. Uygulamanız, kullanıcının isteği üzerine kişileri kaydediyor veya düzenliyorsa yukarıdaki intent'ler, izin ve Google Play Console beyanı olmadan sizi kapsar.

MANAGE_CONTACTS, temel amacı kişileri yönetmek olan ve intent'lerin yeterli olmadığı uygulamalar içindir. Örneğin:

İşleyiş şekli:

• MANAGE_CONTACTS, özel bir uygulama erişim iznidir. Çalışma zamanı iletişim kutusu değildir. Kullanıcılar bu ayarı Ayarlar > Özel uygulama erişimi > Kişileri yönet bölümünden etkinleştirir.

// Opens Settings > Apps > Special app access > Manage contacts
val intent = Intent(Settings.ACTION_MANAGE_CONTACTS, Uri.fromParts("package", packageName, null))
context.startActivity(intent)

• Kişileri, hesapları ve Kişiler Dizini verilerini okuma, ekleme, düzenleme ve silme işlemlerini kapsar. READ_CONTACTS için de istekte bulunmanız gerekmez.
• MANAGE_CONTACTS ile Google Play'de yayınlamak için Play Console'da, intent'lerin uygulamanızın temel işlevi için neden yeterli olmadığını açıklayan bir beyan gönderirsiniz.

Taşıma adımları

• Kişi yazma işlemlerinizi bulma Kodunuzda WRITE_CONTACTS, ContactsContract.RawContacts.CONTENT_URI, ContactsContract.Data.CONTENT_URI ve applyBatch(ContactsContract.AUTHORITY, …) ifadelerini arayın.
• Kullanıcı tarafından yapılan her yazma işlemini bir intent ile değiştirin: Yeni kişiler için ACTION_INSERT, güncellemeler için ACTION_EDIT veya ACTION_INSERT_OR_EDIT.
• Insert.DATA içinde yalnızca standart veri türlerini kullanın. Arama veya mesaj işlemlerini Kişi Dizini'ne taşıyın.
• Yukarıdaki tabloyu kullanarak MANAGE_CONTACTS hizmetine gerçekten ihtiyacınız olup olmadığına karar verin . Kullanıyorsanız Google Play Console beyanınızı planlayın.
• Hiçbir kod yolunun ihtiyacı kalmadığında WRITE_CONTACTS öğesini manifest dosyanızdan kaldırın .

Zaman Çizelgesi

SSS

• Bu durum her uygulamayı etkiler mi?
  • WRITE_CONTACTS desteğinin sonlandırılmasıyla ilgili değişiklik yalnızca yaklaşan Android sürümünü ve sonraki sürümleri hedefleyen uygulamalar için geçerlidir. Eski sürümleri hedefleyen uygulamalar mevcut davranışlarını korur ancak yeni standartlaştırılmış kişi düzenleyici, hedef SDK'larından bağımsız olarak yeni OS'te çalışan tüm uygulamalarda kullanılabilir.
• Uygulamam, intent kullanarak kişileri silebilir mi?
  • Hayır. Kişileri silmek için bir intent yoktur. Kullanıcılar, kişiler uygulamasındaki kişileri silebilir. MANAGE_CONTACTS iznine sahip uygulamalar, kişileri doğrudan silebilir.
• Kendi kişi düzenleme ekranım var. Kullanmaya devam edebilir miyim?
  • Yalnızca uygulamanız MANAGE_CONTACTS için uygunsa. Özel bir tasarımı korumak istemeniz tek başına geçerli bir neden değildir.
• MANAGE_CONTACTS, READ_CONTACTS izninin yerini mi alıyor?
  • MANAGE_CONTACTS, okuma erişimini içerir. Bu nedenle her ikisini de istemeniz gerekmez ancak birçok uygulama, kişileri değiştirmesi gerekmediği halde READ_CONTACTS için uygundur. Bu uygulamalar READ_CONTACTS izni istemeye devam edebilir.
• Android'in eski sürümlerini kullanan kullanıcılarım ne olacak?
  • Kişi intent'leri, cihazın kişiler uygulaması tarafından işlenerek eski sürümlerde de çalışır. Çoğu uygulama, bu intent'leri kullanarak tüm cihazlarda iyi çalışır. Uygulamanız yalnızca en yeni sürümlerde çözülen belirli bir tutarlılık sorunundan etkileniyorsa manifestinizdeki WRITE_CONTACTS iznini uygun bir maxSdkVersion ile kapsamlı tutabilirsiniz.