Pemilih kontak untuk web

Contact Picker API menyediakan cara mudah bagi pengguna untuk membagikan kontak dari daftar kontak mereka.

Pete LePage

Apa itu Contact Picker API?

Akses ke kontak pengguna di perangkat seluler telah menjadi fitur aplikasi iOS/Android sejak (hampir) awal. Ini adalah salah satu permintaan fitur paling umum yang saya dengar dari developer web, dan sering kali menjadi alasan utama mereka membuat aplikasi iOS/Android.

Tersedia mulai Chrome 80 di Android M atau yang lebih baru, spesifikasi Contact Picker API adalah on-demand API yang memungkinkan pengguna memilih entri dari daftar kontak mereka dan membagikan detail terbatas dari entri yang dipilih ke situs. Dengan demikian, pengguna hanya dapat membagikan apa yang mereka inginkan, kapan saja, serta memudahkan pengguna untuk menjangkau dan terhubung dengan teman dan keluarga mereka.

Misalnya, program email berbasis web dapat menggunakan Contact Picker API untuk memilih penerima email. Aplikasi voice-over-IP dapat mencari nomor telepon yang akan dipanggil. Atau jaringan sosial dapat membantu pengguna menemukan teman mana yang telah bergabung.

Menggunakan Contact Picker API

Contact Picker API memerlukan panggilan metode dengan parameter opsi yang menentukan jenis informasi kontak yang Anda inginkan. Metode kedua memberi tahu Anda informasi apa yang akan diberikan sistem yang mendasarinya.

Deteksi fitur

Untuk memeriksa apakah Contact Picker API didukung, gunakan:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

Selain itu, pada Android, Contact Picker memerlukan Android M atau yang lebih baru.

Membuka Pemilih Kontak

Titik entri ke Contact Picker API adalah navigator.contacts.select(). Saat dipanggil, metode ini akan menampilkan promise dan menampilkan pemilih kontak, sehingga pengguna dapat memilih kontak yang ingin mereka bagikan ke situs. Setelah memilih hal yang akan dibagikan dan mengklik Done, promise akan di-resolve dengan array kontak yang dipilih oleh pengguna.

Saat memanggil select(), Anda harus menyediakan array properti yang ingin ditampilkan sebagai parameter pertama (dengan nilai yang diizinkan berupa salah satu dari 'name', 'email', 'tel', 'address', atau 'icon'), dan secara opsional apakah beberapa kontak dapat dipilih sebagai parameter kedua.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

Contacts Picker API hanya dapat dipanggil dari konteks penjelajahan tingkat atas yang aman, dan seperti API canggih lainnya, API ini memerlukan gestur pengguna.

Mendeteksi properti yang tersedia

Untuk mendeteksi properti yang tersedia, panggil navigator.contacts.getProperties(). Metode ini menampilkan promise yang di-resolve dengan array string yang menunjukkan properti mana yang tersedia. Contoh: ['name', 'email', 'tel', 'address']. Anda dapat meneruskan nilai ini ke select().

Ingat, properti tidak selalu tersedia, dan properti baru mungkin ditambahkan. Di masa mendatang, platform dan sumber kontak lain dapat membatasi properti yang dibagikan.

Menangani hasil

Contact Picker API menampilkan array kontak, dan setiap kontak menyertakan array properti yang diminta. Jika kontak tidak memiliki data untuk properti yang diminta, atau pengguna memilih untuk tidak membagikan properti tertentu, API akan menampilkan array kosong. (Saya menjelaskan cara pengguna memilih properti di bagian Kontrol pengguna.)

Misalnya, jika situs meminta name, email, dan tel, lalu pengguna memilih satu kontak yang memiliki data di kolom nama, memberikan dua nomor telepon, tetapi tidak memiliki alamat email, respons yang ditampilkan adalah:

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

Keamanan dan izin

Tim Chrome merancang dan menerapkan Contact Picker API menggunakan prinsip inti yang ditentukan dalam Mengontrol Akses ke Fitur Platform Web yang Canggih, termasuk kontrol pengguna, transparansi, dan ergonomi. Saya akan menjelaskan masing-masingnya.

Kontrol pengguna

Akses ke kontak pengguna dilakukan melalui pemilih, dan hanya dapat dipanggil dengan gestur pengguna, pada konteks penjelajahan tingkat atas yang aman. Hal ini memastikan bahwa situs tidak dapat menampilkan alat pilih saat pemuatan halaman, atau menampilkan alat pilih secara acak tanpa konteks apa pun.

Screenshot, pengguna dapat memilih properti yang akan dibagikan.
Pengguna dapat memilih untuk tidak membagikan beberapa properti. Dalam screenshot ini, pengguna telah menghapus centang pada tombol 'Nomor telepon'. Meskipun situs meminta nomor telepon, nomor tersebut tidak akan dibagikan ke situs.

Tidak ada opsi untuk memilih semua kontak secara massal sehingga pengguna dianjurkan untuk hanya memilih kontak yang perlu mereka bagikan untuk situs tertentu. Pengguna juga dapat mengontrol properti yang dibagikan ke situs dengan mengalihkan tombol properti di bagian atas alat pilih.

Transparansi

Untuk memperjelas detail kontak mana yang dibagikan, alat pilih selalu menampilkan nama dan ikon kontak, serta properti apa pun yang diminta situs. Misalnya, jika sebuah situs meminta name, email, dan tel, ketiga properti tersebut akan ditampilkan di alat pilih. Atau, jika situs hanya meminta tel, alat pilih hanya akan menampilkan nama dan nomor telepon.

Screenshot pemilih untuk situs yang meminta semua properti.
Pemilih, situs yang meminta name, email, dan tel, satu kontak dipilih.
Screenshot pemilih untuk situs yang hanya meminta nomor telepon.
Alat pilih, situs yang hanya meminta tel, satu kontak dipilih.
Screenshot pemilih saat kontak ditekan lama.
Hasil penekanan lama pada kontak.

Menekan lama kontak akan menampilkan semua informasi yang akan dibagikan jika kontak dipilih. (Lihat gambar kontak Cheshire Cat.)

Tidak ada persistensi izin

Akses ke kontak bersifat on demand, dan tidak bertahan. Setiap kali situs menginginkan akses, situs tersebut harus memanggil navigator.contacts.select() dengan gestur pengguna, dan pengguna harus memilih satu per satu kontak yang ingin mereka bagikan dengan situs.

Masukan

Tim Chrome ingin mengetahui pengalaman Anda dengan Contact Picker API.

Ada masalah dengan penerapan?

Apakah Anda menemukan bug pada implementasi Chrome? Atau apakah implementasinya berbeda dengan spesifikasi?

  • Laporkan bug di https://new.crbug.com. Pastikan untuk menyertakan detail sebanyak mungkin, berikan petunjuk sederhana untuk mereproduksi bug, dan tetapkan Komponen ke Blink>Contacts. Glitch sangat cocok untuk berbagi reproduksi masalah dengan cepat dan mudah.

Berencana menggunakan API?

Apakah Anda berencana menggunakan Contact Picker API? Dukungan publik Anda membantu tim Chrome memprioritaskan fitur, dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung fitur tersebut.

Link bermanfaat

Terima kasih

Terima kasih kepada Finnur Thorarinsson dan Rayan Kanso yang menerapkan fitur tersebut, dan Peter Beverloo yang kode-nya tanpa malu-malu saya mencuri dan memfaktorkan ulang untuk demo tersebut.

Catatan: Nama-nama di alat pilih kontak saya adalah karakter dari Alice in Wonderland.