Web için kişi seçici

Contact Picker API, kullanıcıların kişi listelerindeki kişileri paylaşmaları için kolay bir yol sağlar.

Pete LePage

Contact Picker API nedir?

Mobil cihazdaki kullanıcı kişilerine erişim, iOS/Android uygulamalarının neredeyse başlangıcından beri bir özelliğidir. Web geliştiricilerinin en sık dile getirdiği özellik isteklerinden biri bu. Ayrıca iOS/Android uygulaması geliştirmelerinin asıl nedeni de genellikle bu.

Android M veya sonraki sürümlerde Chrome 80'den itibaren kullanılabilen Contact Picker API spesifikasyonu, kullanıcıların iletişim listesinden 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 istediklerini, istedikleri zaman paylaşmasına olanak tanır ve kullanıcıların arkadaşları ve aileleriyle bağlantı kurması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 Kişi Seçici API'yi kullanabilir. IP üzerinden sesli iletişim uygulaması, hangi telefon numarasının aranacağını arayabilir. Sosyal ağlar, kullanıcıların hangi arkadaşlarının daha önce katıldığını keşfetmesine de yardımcı olabilir.

Contact Picker API'sini kullanma

Kişi Seçici API, istediğiniz iletişim bilgisi türlerini belirten bir seçenek parametresi içeren bir yöntem çağrısı gerektirir. İkinci yöntem, temel sistemin hangi bilgileri sağlayacağını size bildirir.

Özellik algılama

Contact Picker API'nin desteklenip desteklenmediğini kontrol etmek için:

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

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

Kişi Seçiciyi Açma

Contact Picker API'sinin giriş noktası navigator.contacts.select(). Çağrıldığında bir promise döndürür ve kişi seçiciyi gösterir. Böylece kullanıcı, siteyle paylaşmak istediği kişileri seçebilir. Nelerin paylaşılacağını seçip Bitti'yi tıkladıktan sonra, kullanıcı tarafından seçilen bir kişi dizisiyle söz çözülür.

select() öğesini çağırırken ilk parametre olarak döndürülmesini istediğiniz bir özellik dizisi (izin verilen değerler 'name', 'email', 'tel', 'address' veya 'icon' seçeneklerinden herhangi biri olacak şekilde) ve isteğe bağlı olarak ikinci parametre olarak birden çok kişinin seçilip seçilemeyeceğini belirtmeniz 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şiler Seçici API yalnızca güvenli ve üst düzey tarama 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ılabilir olduğunu tespit etmek için navigator.contacts.getProperties() işlevini çağırın. Hangi özelliklerin kullanılabilir olduğunu gösteren bir dize dizisiyle çözülen bir söz döndürür. Örnek: ['name', 'email', 'tel', 'address']. Bu değerleri select()'e iletebilirsiniz.

Mülklerin her zaman kullanılamayacağını ve yeni mülkler eklenebileceğini unutmayın. Gelecekte diğer platformlar ve iletişim kaynakları, hangi mülklerin paylaşılabileceğini kısıtlayabilir.

Sonuçları işleme

Kişi Seçici API'si bir kişi dizisi döndürür ve her kişi, istenen mülklerin bir dizisini içerir. Bir kişi istenen mülke ait verilere sahip değilse veya kullanıcı belirli bir mülkü paylaşmayı devre dışı bırakmayı seçerse API boş bir dizi döndürür. (Kullanıcıların tesisleri nasıl seçtiğini Kullanıcı kontrolü bölümünde açıklıyorum.)

Örneğin, bir site name, email ve tel'yi isterse ve bir kullanıcı ad alanında veri olan tek bir kişiyi seçerse, iki telefon numarası sağlar ancak e-posta adresi sağlamazsa döndürülen yanıt şu olur:

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

Güvenlik ve izinler

Chrome ekibi, Kişi Seçici API'yi tasarlarken ve uygularken kullanıcı kontrolü, şeffaflık ve ergonomi gibi Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme başlıklı makalede tanımlanan temel ilkeleri kullandı. Her birini açıklayacağım.

Kullanıcı denetimi

Kullanıcıların kişilerine erişim, seçici aracılığıyla sağlanır ve yalnızca güvenli, üst düzey bir tarama bağlamında kullanıcı hareketiyle çağrılabilir. Bu, sitelerin sayfa yüklendiğinde seçiciyi gösterememesini veya herhangi bir bağlam olmadan rastgele seçiciyi gösterememesini sağlar.

Ekran görüntüsü, kullanıcılar hangi mülkleri paylaşacaklarını seçebilir.
Kullanıcılar bazı mülkleri paylaşmamayı seçebilir. Bu ekran görüntüsünde, kullanıcının "Telefon numaraları" düğmesinin işaretini kaldırdığı görülüyor. Site telefon numarası istemiş olsa bile bu numaralar siteyle paylaşılmaz.

Tüm kişileri toplu olarak seçme seçeneği yoktur. Bu nedenle, kullanıcıların yalnızca belirli bir web sitesi için paylaşmaları gereken kişileri seçmeleri önerilir. Kullanıcılar, seçicinin üst kısmındaki mülk düğmesini açarak siteyle hangi mülklerin paylaşıldığı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ı ve simgesini, ayrıca sitenin istediği tüm özellikleri gösterir. Örneğin, bir site name, email ve tel özelliklerini isterse seçicide üç özellik de gösterilir. Alternatif olarak, bir site yalnızca tel isterse seçici yalnızca adı ve telefon numaralarını gösterir.

Tüm özellikleri isteyen site için seçicinin ekran görüntüsü.
Seçici, name, email ve tel isteyen site, bir kişi seçili.
Yalnızca telefon numarası isteyen site için seçicinin ekran görüntüsü.
Seçici, yalnızca tel isteyen site, bir kişi seçili.
Bir kişiye uzun basıldığında seçicinin ekran görüntüsü.
Bir kişiye uzun basmanın sonucu.

Bir kişiye uzun bastığınızda, kişi seçilirse paylaşılacak tüm bilgiler gösterilir. (Cheshire Cat'in kişi resmine bakın.)

İzin kalıcı değil

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

Geri bildirim

Chrome Ekibi, Kişi Seçici API'siyle ilgili deneyimlerinizi öğrenmek istiyor.

Uygulamayla ilgili sorun mu yaşıyorsunuz?

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

  • https://new.crbug.com adresinden hata kaydı oluşturun. Mümkün olduğunca fazla ayrıntı eklediğinizden, hatayı yeniden oluşturmayla ilgili basit talimatlar sağladığınızdan ve Bileşenler'i Blink>Contacts olarak ayarladığınızdan emin olun. Glitch, sorunların hızlı ve kolay bir şekilde yeniden oluşturulmasını paylaşmak için mükemmel bir araçtır.

API'yi kullanmayı planlıyor musunuz?

Contact Picker API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özelliklere öncelik vermesine yardımcı olur ve diğer tarayıcı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

Faydalı bağlantılar

Teşekkürler

Özelliği uygulayan Finnur Thorarinsson ve Rayan Kanso'ya ve kodunu utanmadan çaldığım ve demo için yeniden derlediğim Peter Beverloo'ya teşekkür ederiz.

Not: Kişi seçicimdeki adlar, Alice Harikalar Diyarında'daki karakterlerden alınmıştır.