Web için kişi seçici

Kişi Seçici API'sı, kullanıcıların kişi listelerindeki kişileri paylaşmaları için kolay bir yol sağlar.

Pete LePage

Contact Picker API nedir?

Kullanıcının kişilerine mobil cihazlardan erişme özelliği, neredeyse zamanın başından beri iOS/Android uygulamalarının bir özelliği olmuştur. Bu, web geliştiricilerinin en sık duyduğu özellik isteklerinden biri ve genellikle iOS/Android uygulaması oluşturmalarının da en önemli nedeni.

Android M veya sonraki sürümlerde Chrome 80'de bulunan Contact Picker API spesifikasyonu, kullanıcıların kişi listelerinden girişler seçmesine ve seçilen girişlerin sınırlı ayrıntılarını bir web sitesiyle paylaşmasına olanak tanıyan isteğe bağlı bir API'dir. Kullanıcıların yalnızca istedikleri içeriği istedikleri zaman paylaşmalarına olanak tanıyan bu özellik; kullanıcıların, arkadaşlarına ve ailelerine ulaşıp onlarla bağlantı kurmalarını kolaylaştırır.

Örneğin, web tabanlı bir e-posta istemcisi, bir e-postanın alıcılarını seçmek için Contact Picker API'yi kullanabilir. Bir seslendirme IP uygulaması hangi telefon numarasını arayacağını arayabilir. Ya da sosyal ağ, kullanıcının katılan arkadaşlarını keşfetmesine yardımcı olabilir.

Kişi Seçici API'sini kullanma

Contact Picker API, istediğiniz iletişim bilgisi türlerini belirten bir seçenekler parametresi içeren bir yöntem çağrısı gerektirir. İkinci yöntem ise temel sistemin hangi bilgileri sağlayacağını söyler.

Özellik algılama

Contact Picker API'nin desteklenip desteklenmediğini kontrol etmek için şunları kullanın:

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

Ayrıca, Android'de Kişi Seçici için Android M veya daha yeni bir sürüm gereklidir.

Kişi Seçiciyi Açma

Contact Picker API'nin giriş noktası navigator.contacts.select(). Çağrı yapıldığında bir söz verilir ve kişi seçiciyi gösterir. Böylece kullanıcının siteyle paylaşmak istediği kişileri seçmesine olanak sağlanır. Neyi paylaşacağınızı seçip Bitti'yi tıkladıktan sonra, söz konusu kullanıcı tarafından seçilen bir dizi kişi sonlandırılır.

select() yöntemini çağırırken ilk parametre olarak döndürülmesini istediğiniz (izin verilen değerlerin 'name', 'email', 'tel', 'address' veya 'icon' değerlerinden herhangi biri) ve isteğe bağlı olarak ikinci parametre olarak birden fazla kişinin seçilip seçilemeyeceğine ilişkin bir özellik dizisi sağlamanız gerekir.

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.
}

Kişi Seçici API yalnızca güvenli, üst düzey bir göz atma bağlamından çağrılabilir ve diğer güçlü API'ler gibi bir kullanıcı hareketi gerektirir.

Kullanılabilir mülkleri algılama

Hangi tesislerin kullanılabildiğini tespit etmek için navigator.contacts.getProperties() çağrısı yapın. Hangi özelliklerin kullanılabilir olduğunu belirten bir dize dizisiyle çözümlenen bir söz döndürür. Örneğin: ['name', 'email', 'tel', 'address']. Bu değerleri select() işlevine iletebilirsiniz.

Mülklerin her zaman kullanılamadığını ve yeni mülkler eklenebileceğini unutmayın. Gelecekte diğer platformlar ve kişi kaynakları, paylaşılacak mülkleri kısıtlayabilir.

Sonuçları işleme

Contact Picker API, bir kişi dizisi döndürür ve her kişi, istenen özelliklerin bir dizisini içerir. Bir kişinin, istenen mülk için verisi yoksa veya kullanıcı belirli bir mülkün paylaşılmasını devre dışı bırakmayı seçerse API boş bir dizi döndürür. (Kullanıcının mülkleri nasıl seçtiğini Kullanıcı denetimi bölümünde açıkladım.)

Örneğin, bir site name, email ve tel isteğinde bulunursa ve bir kullanıcı, ad alanında veri bulunan tek bir kişi seçerse, iki telefon numarası sağlar ancak e-posta adresi yoksa verilen yanıt şöyle olur:

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

Güvenlik ve izinler

Chrome ekibi, Contact Picker API'yi Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme bölümünde tanımlanan kullanıcı denetimi, şeffaflık ve ergonomi gibi temel ilkeleri kullanarak tasarladı ve uyguladı. Her birini açıklayacağım.

Kullanıcı denetimi

Kullanıcıların kişilerine erişim seçici aracılığıyla yapılır ve bu erişim, güvenli ve üst düzey bir göz atma bağlamında yalnızca bir kullanıcı hareketiyle çağrılabilir. Bu, sitenin sayfa yüklenirken seçiciyi veya seçiciyi herhangi bir bağlam olmadan rastgele göstermesini önler.

Ekran görüntüsü, kullanıcılar hangi özelliklerin paylaşılacağını seçebilir.
Kullanıcılar bazı tesisleri paylaşmamayı seçebilir. Bu ekran görüntüsünde, kullanıcı "Telefon numaraları" düğmesinin işaretini kaldırmıştır. Site, telefon numaraları istese bile bu numaralar siteyle paylaşılmaz.

Tüm kişileri toplu olarak seçme seçeneği yoktur. Böylece kullanıcıların yalnızca söz konusu web sitesi için paylaşmaları gereken kişileri seçmeleri teşvik edilir. Ayrıca kullanıcılar, seçicinin üst kısmındaki mülk düğmesini açıp kapatarak hangi mülklerin siteyle paylaşılacağını da kontrol edebilir.

Şeffaflık

Hangi iletişim bilgilerinin paylaşıldığını netleştirmek için seçici her zaman kişinin adını, simgesini ve sitenin istediği özellikleri gösterir. Örneğin, bir site name, email ve tel isteğinde bulunursa seçicide üç mülkün tamamı gösterilir. Alternatif olarak, bir site yalnızca tel isteğinde bulunursa seçici yalnızca adı ve telefon numaralarını gösterir.

Tüm mülklerin istendiği site seçicinin ekran görüntüsü.
Seçici; name, email ve tel isteyen site, bir kişi seçildi.
Yalnızca telefon numarası isteyen sitenin seçicisinin ekran görüntüsü.
Seçici, yalnızca tel isteğinde bulunan site, bir kişi seçildi.
Bir kişiye uzun basıldığındaki seçicinin ekran görüntüsü.
Kişiye uzun basmanın sonucu.

Bir kişiye uzun basıldığında, kişinin seçilmesi halinde paylaşılacak tüm bilgiler gösterilir. (Cheshire Cat iletişim resmine bakın.)

İzin kalıcılığı yok

Kişilere erişim isteğe bağlıdır ve kalıcı değildir. Bir site her erişim istediğinde, bir kullanıcı hareketiyle navigator.contacts.select() çağrısı yapmalı ve kullanıcının siteyle paylaşmak istediği kişileri tek tek seçmesi gerekir.

Geri bildirim

Chrome ekibi, Contact Picker API ile ilgili deneyimlerinizi öğrenmek istiyor.

Uygulamayla ilgili bir sorun mu var?

Chrome'un uygulamasında bir hata buldunuz mu? Yoksa uygulama, spesifikasyondan farklı mı?

  • https://new.crbug.com adresinden hata bildiriminde bulunun. Mümkün olduğunca fazla ayrıntı eklediğinizden, hatayı yeniden oluşturmak için basit talimatlar sağladığınızdan ve Bileşenler'i Blink>Contacts olarak ayarladığınızdan emin olun. Glitch, sorunları hızlı ve kolay bir şekilde yeniden oluşturmak için idealdir.

API'yi kullanmayı mı planlıyorsunuz?

Kişi Seçici API'sini kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özellikleri öncelik sırasına koymasına yardımcı olur ve diğer tarayıcı tedarikçilerine, bu özellikleri desteklemenin ne kadar kritik olduğunu gösterir.

Faydalı bağlantılar

Teşekkürler

Hepinize teşekkür ederim. Özelliği uygulayan Finnur Thorarinsson ve Rayan Kanso ile kodunu utanmadan çalıştığım ve demo için yeniden düzenlediğim Peter Beverloo'ya teşekkür ederiz.

Not: Kişi seçicimdeki adlar, Ayşe Harikalar Diyarında'dan karakterler.