Cara yang lebih andal untuk menambahkan dan mengedit kontak di Android

Yang berubah

Aplikasi yang menargetkan rilis Android mendatang tidak akan dapat lagi menulis langsung ke kontak dengan izin WRITE_CONTACTS. Sebagai gantinya, Anda dapat menggunakan intent kontak standar (ACTION_INSERT, ACTION_EDIT, dan ACTION_INSERT_OR_EDIT). Untuk mengetahui implementasi referensi lengkap, lihat panduan developer tentang cara mengubah kontak menggunakan intent. 

Di perangkat yang menjalankan rilis Android mendatang, ketiga intent kontak ini akan berperilaku secara konsisten dan tidak memerlukan izin sama sekali. Jika aplikasi Anda menargetkan rilis Android mendatang atau yang lebih baru dan mencoba menulis ke kontak secara langsung, penulisan tersebut akan ditolak dan menghasilkan SecurityException atau penolakan izin. Untuk sejumlah kecil aplikasi yang memerlukan akses luas untuk membuat dan mengubah kontak, izin akses aplikasi khusus baru, MANAGE_CONTACTS, akan hadir di Android 17 QPR2 (Q4 2026). Google Play memublikasikan panduan terbaru untuk akses kontak, termasuk MANAGE_CONTACTS, hari ini.

Alasan kami melakukan perubahan ini

Saat ini, jika aplikasi Anda perlu menyimpan satu kontak saja, Anda mungkin meminta WRITE_CONTACTS. Namun, izin tersebut memberikan akses yang luas, sehingga aplikasi dapat membuat perubahan yang meluas pada kontak di seluruh perangkat di latar belakang, bahkan tanpa interaksi pengguna. Sebagian besar aplikasi tidak memerlukan izin yang luas.

Meskipun ada alternatif, kami telah menerima masukan dari Anda bahwa alternatif tersebut perlu lebih distandardisasi di seluruh ekosistem. Sebelumnya, intent kontak berperilaku berbeda dari satu perangkat ke perangkat lainnya. Beberapa editor menghapus data yang Anda teruskan, seperti foto kontak. Di beberapa perangkat, tombol kembali menyimpan kontak tanpa disengaja oleh pengguna atau opsi "buat kontak baru" sulit ditemukan. Jadi, meminta izin adalah pilihan yang rasional. Kami sedang memperbaiki semua masalah ini di versi Android mendatang dan mewajibkan perangkat yang menjalankannya untuk mengikuti standar yang sama.

Yang harus digunakan sebagai gantinya

Menambahkan atau mengedit kontak: menggunakan intent kontak

Saat Anda menggunakan intent ini - ACTION_INSERT, ACTION_EDIT, dan ACTION_INSERT_OR_EDIT - sistem akan menangani tugas berat dengan menampilkan pengalaman editor kontak yang rapi dan terstandardisasi. Tindakan ini akan membuka formulir setengah halaman cepat untuk entri baru, atau memungkinkan pengguna menelusuri dan menambahkan informasi ke kontak yang ada dengan mudah. Pengguna dapat dengan lancar memperluasnya menjadi editor halaman penuh untuk mengisi detail selengkapnya, semuanya tanpa perlu izin tulis langsung dari aplikasi Anda. Lihat tiruan UX tentatif di bawah: 

Gambar 1: Membuat Kontak Baru  *UX belum Final*

Gambar 2: Menambahkan Info ke Kontak yang Ada *UX Belum Final*

Catatan: Produsen perangkat yang berbeda dapat mengubah pengalaman pengguna agar sesuai dengan gaya OS mereka, tetapi perilakunya akan tetap konsisten.

Anda dapat lebih menyederhanakan proses pembuatan dengan meneruskan payload data opsional, yang dikenal sebagai Tambahan, bersama dengan intent Anda:

• EXTRA_ACCOUNT menyarankan akun tempat kontak disimpan, yang membantu jika aplikasi Anda menyinkronkan kontak. Fitur tambahan ini sudah ada, tetapi dukungannya bervariasi menurut perangkat. Mulai rilis Android mendatang, dukungan akan distandardisasi di seluruh perangkat.
• EXTRA_PHOTO_URI meneruskan foto untuk mengisi otomatis foto kontak. Editor akan menangani izin baca URI untuk Anda. Fitur ini baru tersedia di rilis Android mendatang dan akan didukung di seluruh ekosistem.

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

Memilih kontak: menggunakan Pemilih Kontak

Jika Anda hanya perlu membaca kontak yang dipilih pengguna, gunakan Pemilih Kontak, yang tersedia sejak Android 17. Aplikasi ini tidak memerlukan izin.

Aplikasi panggilan telepon dan pesan: menggunakan Direktori Profil

Beberapa aplikasi menambahkan tindakan "Telepon dengan…" atau "Kirim pesan dengan…" ke kontak sehingga orang dapat memulai panggilan atau chat dari aplikasi Telepon atau Kontak. Jika aplikasi Anda melakukan hal ini sekarang dengan menulis entri tambahan ke kontak pengguna, pindah ke Direktori Orang, yang akan hadir di Android QPR2 (Q4 2026). Ini adalah direktori sistem baru tempat aplikasi Anda memublikasikan cara orang dapat saling menghubungi di aplikasi Anda, tanpa mengedit kontak pengguna.

Contoh cara aplikasi dapat bermigrasi

Untuk melihat cara kerja alternatif ini dalam praktiknya, berikut beberapa contoh cara berbagai jenis aplikasi dapat mengakses kontak:

Perubahan yang harus diperiksa

• Jenis data kustom tidak didukung di editor. Jika Anda meneruskan baris Insert.DATA dengan jenis MIME selain jenis ContactsContract.CommonDataKinds standar, jenis MIME tersebut akan diabaikan secara otomatis oleh editor.
• SHOW_OR_CREATE_CONTACT tidak ditangani oleh editor sistem. Aplikasi kontak bawaan perangkat masih dapat menanganinya. Untuk perilaku yang konsisten di seluruh perangkat, gunakan ACTION_INSERT_OR_EDIT.
• Penulisan gagal secara default. Setelah Anda menargetkan rilis Android mendatang, penulisan langsung tanpa MANAGE_CONTACTS akan menghasilkan SecurityException or permission denial. Uji keberadaannya.

Apakah saya memerlukan MANAGE_CONTACTS?

Mungkin tidak. Jika aplikasi Anda menyimpan atau mengedit kontak karena diminta oleh pengguna, intent di atas akan mencakup Anda, tanpa izin dan tanpa pernyataan Konsol Play.

MANAGE_CONTACTS ditujukan untuk aplikasi yang tujuan intinya adalah mengelola kontak, yang tidak cukup hanya menggunakan intent. Contoh:

Cara kerjanya:

• MANAGE_CONTACTS adalah izin akses aplikasi khusus. Dialog ini bukan dialog runtime. Pengguna dapat mengaktifkannya di Setelan > Akses aplikasi khusus > Kelola kontak.

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

• Cakupan ini meliputi membaca, menambahkan, mengedit, dan menghapus kontak, akun, dan data Direktori Profil. Anda juga tidak perlu meminta READ_CONTACTS.
• Untuk memublikasikan aplikasi di Google Play dengan MANAGE_CONTACTS, Anda harus mengirimkan pernyataan di Konsol Play yang menjelaskan alasan intent tidak cukup untuk fungsi inti aplikasi Anda.

Langkah-langkah migrasi

• Temukan penulisan kontak Anda. Telusuri kode Anda untuk menemukan WRITE_CONTACTS, ContactsContract.RawContacts.CONTENT_URI, ContactsContract.Data.CONTENT_URI, dan applyBatch(ContactsContract.AUTHORITY, …).
• Ganti setiap penulisan yang didorong pengguna dengan intent: ACTION_INSERT untuk kontak baru, dan ACTION_EDIT atau ACTION_INSERT_OR_EDIT untuk update.
• Hanya gunakan jenis data standar di Insert.DATA. Memindahkan tindakan panggilan atau pesan ke Direktori Orang.
• Tentukan apakah Anda benar-benar memerlukan MANAGE_CONTACTS menggunakan tabel di atas. Jika ya, rencanakan pernyataan Konsol Play Anda.
• Hapus WRITE_CONTACTS dari manifes Anda setelah tidak ada alur kode yang memerlukannya.

Linimasa

FAQ

• Apakah hal ini memengaruhi setiap aplikasi?
  • Perubahan penghentian penggunaan WRITE_CONTACTS hanya berlaku untuk aplikasi yang menargetkan rilis Android mendatang dan setelahnya. Aplikasi yang menargetkan versi lama akan mempertahankan perilakunya saat ini, tetapi editor kontak standar yang baru akan tersedia untuk semua aplikasi yang berjalan di OS baru, terlepas dari SDK targetnya.
• Dapatkah aplikasi saya menghapus kontak dengan intent?
  • Tidak. Tidak ada intent untuk menghapus kontak. Pengguna menghapus kontak di aplikasi kontak mereka. Aplikasi dengan MANAGE_CONTACTS dapat menghapus kontak secara langsung.
• Saya sudah memiliki layar pengeditan kontak sendiri. Dapatkah saya menyimpannya?
  • Hanya jika aplikasi Anda memenuhi syarat untuk MANAGE_CONTACTS. Keinginan untuk mempertahankan desain kustom bukanlah alasan yang memenuhi syarat.
• Apakah MANAGE_CONTACTS menggantikan READ_CONTACTS?
  • MANAGE_CONTACTS mencakup akses baca sehingga Anda tidak perlu meminta keduanya, tetapi banyak aplikasi yang memenuhi syarat untuk READ_CONTACTS yang tidak perlu mengubah kontak sama sekali. Aplikasi ini dapat terus meminta READ_CONTACTS.
• Bagaimana dengan pengguna saya yang menggunakan versi Android lama?
  • Intent kontak juga berfungsi pada versi lama, yang ditangani oleh aplikasi kontak perangkat. Sebagian besar aplikasi akan berfungsi dengan baik di semua perangkat menggunakan intent ini. Jika aplikasi Anda terpengaruh oleh masalah konsistensi tertentu yang hanya diselesaikan dalam versi terbaru, Anda dapat mempertahankan izin WRITE_CONTACTS dalam manifes yang dicakup dengan maxSdkVersion yang sesuai.