Selektor kontaktów w internecie

Interfejs Contact Picker API umożliwia użytkownikom łatwe udostępnianie kontaktów z ich listy kontaktów.

Pete LePage

Czym jest interfejs Contact Picker API?

Dostęp do kontaktów użytkownika na urządzeniu mobilnym jest funkcją aplikacji na iOS i Androida od (prawie) zarania dziejów. To jedna z najczęstszych próśb o wprowadzenie funkcji, jakie słyszę od web developerów, i często jest to kluczowy powód, dla którego tworzą aplikacje na iOS/Androida.

Specyfikacja interfejsu Contact Picker API jest dostępna od wersji Chrome 80 na Androida M lub nowszej. Jest to interfejs API na żądanie, który umożliwia użytkownikom wybieranie pozycji z listy kontaktów i udostępnianie ograniczonych informacji o wybranych pozycjach witrynie. Pozwala użytkownikom udostępniać tylko to, co chcą i kiedy chcą, oraz ułatwia im kontakt z rodziną i znajomymi.

Internetowy klient poczty e-mail może na przykład używać interfejsu Contact Picker API do wybierania odbiorców e-maila. Aplikacja VoIP może sprawdzić, na jaki numer telefonu zadzwonić. Sieć społecznościowa może też pomóc użytkownikowi dowiedzieć się, którzy znajomi już do niej dołączyli.

Korzystanie z interfejsu Contact Picker API

Interfejs Contact Picker API wymaga wywołania metody z parametrem opcji, który określa wymagane typy informacji kontaktowych. Druga metoda informuje, jakie informacje udostępni system bazowy.

Wykrywanie cech

Aby sprawdzić, czy interfejs Contact Picker API jest obsługiwany, użyj:

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

Dodatkowo na Androidzie selektor kontaktów wymaga Androida w wersji M lub nowszej.

Otwieranie selektora kontaktów

Punkt wejścia do interfejsu Contact Picker API to navigator.contacts.select(). Po wywołaniu zwraca obietnicę i wyświetla selektor kontaktów, umożliwiając użytkownikowi wybranie kontaktów, które chcą udostępnić witrynie. Po wybraniu elementów do udostępnienia i kliknięciu Gotowe obietnica zostanie spełniona, a użytkownik zobaczy tablicę z wybranymi przez niego kontaktami.

W wywołaniu funkcji select() jako pierwszy parametr musisz podać tablicę właściwości, które mają zostać zwrócone (dozwolone wartości to 'name', 'email', 'tel', 'address' lub 'icon'), a jako drugi parametr opcjonalnie możesz podać, czy można wybrać wiele kontaktów.

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

Interfejs Contacts Picker API może być wywoływany tylko z bezpiecznego kontekstu przeglądania najwyższego poziomu. Podobnie jak inne potężne interfejsy API wymaga on działania użytkownika.

Wykrywanie dostępnych usług

Aby sprawdzić, które właściwości są dostępne, wywołaj navigator.contacts.getProperties(). Zwraca obietnicę rozwiązaną za pomocą tablicy ciągów znaków wskazujących, które właściwości są dostępne. Na przykład: ['name', 'email', 'tel', 'address']. Te wartości możesz przekazać do select().

Pamiętaj, że właściwości nie zawsze są dostępne i mogą pojawiać się nowe właściwości. W przyszłości inne platformy i inne źródła kontaktów mogą ograniczyć, które usługi mają być udostępniane.

Obsługa wyników

Interfejs Contact Picker API zwraca tablicę kontaktów, a każdy kontakt zawiera tablicę żądanych właściwości. Jeśli kontakt nie ma danych dotyczących żądanej usługi lub użytkownik zrezygnuje z udostępniania określonej usługi, interfejs API zwróci pustą tablicę. (sposób wybierania właściwości przez użytkownika opisuję w sekcji Kontrola użytkownika).

Jeśli na przykład witryna prosi o dane name, email i tel, a użytkownik wybierze jeden kontakt z danymi w polu z nazwami, poda 2 numery telefonów, ale nie poda adresu e-mail, odpowiedź będzie następująca:

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

Zabezpieczenia i uprawnienia

Zespół Chrome zaprojektował i wdrżał interfejs Contact Picker API, korzystając z podstawowych zasad zdefiniowanych w artykule Kontrolowanie dostępu do zaawansowanych funkcji platformy internetowej, w tym kontroli użytkownika, przejrzystości i ergonomiki. Wyjaśnię je po kolei.

Kontrola użytkownika

Dostęp do kontaktów użytkownika jest możliwy za pomocą selektora i może być wywoływany tylko przez użytkownika w bezpiecznym kontekście przeglądania na najwyższym poziomie. Dzięki temu witryna nie będzie wyświetlać selektora podczas wczytywania strony ani nie będzie wyświetlana w sposób losowy bez żadnego kontekstu.

Zrzut ekranu pokazujący, jak użytkownicy mogą wybrać usługi, które chcą udostępnić.
Użytkownicy mogą nie udostępniać niektórych usług. Na tym zrzucie ekranu użytkownik odznaczył opcję „Numery telefonów”. Mimo że witryna prosi o numery telefonów, nie będą one udostępniane.

Nie ma opcji zbiorczego wybierania wszystkich kontaktów, dlatego zachęcamy użytkowników do wybierania tylko tych kontaktów, które chcą udostępnić w konkretnej witrynie. Użytkownicy mogą też kontrolować, które usługi są udostępniane witrynie, przełączając przycisk usługi u góry selektora.

Przejrzystość

Aby ułatwić określenie, które dane kontaktowe są udostępniane, selektor zawsze wyświetla nazwę i ikonę kontaktu oraz wszystkie właściwości, których zażądała witryna. Jeśli na przykład witryna prosi o usługi name, email i tel, w selektorze pojawią się wszystkie 3 usługi. Jeśli witryna poprosi tylko o tel, selektor wyświetli tylko nazwę i numery telefonów.

Zrzut ekranu z selektorem witryny, który prosi o wszystkie usługi
Wybieranie, witryna prosząca o dostęp do name, email i tel, wybrany jeden kontakt.
Zrzut ekranu selektora w witrynie, która prosi tylko o numery telefonów
Selektor, witryna żąda tylko tel, wybrano 1 kontakt.
Zrzut ekranu z wyświetlanego selektora po przytrzymaniu kontaktu.
Wynik długotrwałego naciśnięcia kontaktu.

Przytrzymanie kontaktu spowoduje wyświetlenie wszystkich informacji, które zostaną udostępnione po jego wybraniu. (patrz obrazek kontaktu Kot z buławą).

Brak trwałości uprawnień

Dostęp do kontaktów jest dostępny na żądanie i nie jest trwały. Za każdym razem, gdy witryna chce uzyskać dostęp, musi wywołać metodę navigator.contacts.select() po wykonaniu przez użytkownika odpowiedniego działania, a użytkownik musi wybrać kontakty, które chce udostępnić witrynie.

Prześlij opinię

Zespół Chrome chce poznać Twoją opinię na temat interfejsu API selektora kontaktów.

Problem z implementacją?

Czy wystąpił błąd związany z implementacją Chrome? Czy implementacja różni się od specyfikacji?

  • Zgłoś błąd na https://new.crbug.com. Podaj jak najwięcej szczegółów, podaj proste instrukcje odtworzenia błędu i ustaw opcję Komponenty na Blink>Contacts. Glitch świetnie sprawdza się do udostępniania szybkich i łatwych sposobów odtworzenia problemów.

Planujesz korzystać z interfejsu API?

Zamierzasz używać interfejsu Contact Picker API? Twoje publiczne wsparcie pomaga zespołowi Chrome ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie.

Przydatne linki

Dziękujemy

Wielkie podziękowania dla Finnura Thorarinssona i Rayana Kanso, którzy wdrożą tę funkcję, oraz Petera Beverloo, którego kod bezwstydnie skradliśmy i przerobiliśmy na potrzeby demonstracji.

P.S. Imiona i nazwiska w selektorze kontaktów to znaki z Alicji w Krainie Czarów.