Pemilih kontak untuk web

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

Apa itu Contact Picker API?

Akses ke kontak pengguna pada perangkat seluler telah menjadi fitur aplikasi iOS/Android sejak (hampir) fajar. Ini adalah salah satu permintaan fitur yang paling umum Saya mendengar masukan dari para developer web, dan sering kali menjadi alasan utama mereka membuat iOS/Android .

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

Misalnya, program email berbasis web bisa menggunakan Contact Picker API untuk pilih penerima email. Aplikasi voice-over-IP dapat mencari nomor telepon yang akan dihubungi. Atau jejaring 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 disediakan oleh sistem yang mendasarinya.

Deteksi fitur

Untuk memeriksa apakah Contact Picker API didukung, gunakan:

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

Selain itu, di Android, Pemilih Kontak memerlukan Android M atau yang lebih baru.

Membuka Pemilih Kontak

Titik entri ke Contact Picker API adalah navigator.contacts.select(). Ketika dipanggil, fungsi ini akan menampilkan promise dan menampilkan pemilih kontak, sehingga memungkinkan pengguna untuk memilih kontak yang ingin mereka bagikan ke situs. Sesudah memilih apa yang akan dibagikan dan mengklik Selesai, promise akan di-resolve dengan array kontak yang dipilih oleh pengguna.

Saat memanggil select(), Anda harus memberikan array properti yang diinginkan dikembalikan 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 metode aman, konteks penjelajahan tingkat atas, dan seperti API canggih lainnya, hal ini memerlukan gestur pengguna.

Mendeteksi properti yang tersedia

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

Ingat, properti tidak selalu tersedia, dan properti baru mungkin ditambahkan. Pada masa mendatang, platform dan sumber kontak lain mungkin akan membatasi properti mana 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 tidak ikut berbagi , API akan menampilkan array kosong. (Saya menjelaskan cara pengguna memilih properti di bagian Kontrol pengguna.)

Misalnya, jika situs meminta name, email, dan tel, serta pengguna memilih satu kontak yang memiliki data di isian 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 mengimplementasikan Contact Picker API menggunakan API yang didefinisikan dalam Mengontrol Akses ke Fitur Platform Web yang Andal, termasuk kontrol pengguna, transparansi, dan ergonomi. Saya akan menjelaskannya masing-masing.

Kontrol pengguna

Akses ke kontak 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 pemilih saat pemuatan halaman, atau menampilkan secara acak pemilih tanpa konteks apa pun.

Screenshot, pengguna dapat memilih properti yang akan dibagikan.
Pengguna dapat memilih untuk tidak membagikan beberapa properti. Dalam screenshot ini, pengguna tidak mencentang 'Nomor telepon' tombol. Meskipun situs ini meminta nomor telepon, nomor tersebut tidak akan dibagikan dengan situs.

Tidak ada opsi untuk memilih semua kontak secara massal sehingga pengguna terdorong untuk memilih hanya kontak yang perlu dibagikan untuk situs Anda. Pengguna juga dapat mengontrol properti yang dibagikan ke situs dengan mengalihkan tombol properti di bagian atas pemilih.

Transparansi

Untuk mengklarifikasi detail kontak mana yang dibagikan, alat pilih selalu menampilkan nama dan ikon kontak, serta properti apa pun yang dimiliki situs diminta. Misalnya, jika situs meminta name, email, dan tel, ketiga properti tersebut akan ditampilkan di pemilih. Sebagai alternatif, jika situs hanya meminta tel, alat pilih hanya akan menampilkan nama, dan nomor telepon Anda.

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.
Picker, situs hanya meminta tel, satu kontak dipilih.
Screenshot pemilih saat kontak ditekan lama.
Akibat menekan lama pada kontak.

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

Tidak ada persistensi izin

Akses ke kontak sesuai permintaan, dan tidak dipertahankan. Setiap kali situs ingin akses, objek tersebut harus memanggil navigator.contacts.select() dengan gestur pengguna, dan pengguna harus memilih satu per satu kontak yang ingin dibagikan dengan situs.

Masukan

Tim Chrome ingin mengetahui pengalaman Anda saat menggunakan Pemilih Kontak Compute Engine API.

Ada masalah dengan implementasinya?

Apakah Anda menemukan bug pada implementasi Chrome? Ataukah implementasi berbeda dengan spesifikasi?

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

Anda berencana menggunakan API?

Anda berencana menggunakan Contact Picker API? Dukungan publik Anda membantu Tim Chrome memprioritaskan fitur, dan menunjukkan kepada vendor browser lainnya cara pentingnya mendukung mereka.

Link bermanfaat

Terima kasih

Terima kasih banyak kepada Finnur Thorarinsson dan Rayan Kanso yang menerapkan fitur tersebut dan Peter Beverloo yang kode saya tanpa malu mencuri dan difaktorkan ulang untuk demo.

N.B.: Nama-nama di pemilih kontak saya adalah karakter dari Alice in Wonderland.