Selektor kontaktów w internecie

Interfejs API selektora kontaktów pozwala użytkownikom w prosty sposób udostępniać kontakty ze swojej listy kontaktów.

Pete LePage

Co to jest interfejs API selektora kontaktów?

Dostęp do kontaktów użytkownika na urządzeniu mobilnym jest funkcją dostępną w aplikacjach na iOS i Androida od samego początku. To jedna z najczęstszych próśb o dodanie funkcji, jakie otrzymujemy od programistów internetowych, i często jest to główny powód, dla którego tworzą aplikacje na iOS lub Androida.

Specyfikacja interfejsu Contact Picker API, dostępna w Chrome 80 na urządzeniach z Androidem M lub nowszym, to interfejs API na żądanie, który umożliwia użytkownikom wybieranie wpisów z listy kontaktów i udostępnianie witrynom ograniczonych szczegółów wybranych wpisów. Pozwala użytkownikom dzielić się tylko tym, co chcą i kiedy chcą. Ułatwia to też użytkownikom kontakt ze znajomymi i rodziną oraz kontaktowanie się z nimi.

Na przykład internetowy klient poczty e-mail może użyć interfejsu Contact Picker API do wybrania adresatów e-maila. Aplikacja odczytywana przez głos głosowy może wyszukać numer telefonu, pod który należy zadzwonić. Sieć społecznościowa może też pomóc użytkownikowi w odkryciu znajomych, którzy już dołączyli do społeczności.

Korzystanie z interfejsu Contact Picker API

Interfejs Contact Picker API wymaga wywołania metody z parametrem „options” określający typ potrzebnych informacji kontaktowych. Druga metoda informuje, jakie informacje dostarczy system bazowy.

Wykrywanie funkcji

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

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

Ponadto na urządzeniach z Androidem selektor kontaktów wymaga Androida M lub nowszego.

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 chce udostępnić witrynie. Gdy wybierzesz, co chcesz udostępnić, i klikniesz Gotowe, obietnica zniknie dzięki tablicy kontaktów wybranej przez użytkownika.

Wywołując funkcję select(), musisz podać tablicę właściwości, która ma być zwracana jako pierwszy parametr (dozwolonymi wartościami są: 'name', 'email', 'tel', 'address' lub 'icon'). Opcjonalnie możesz też określić, czy jako drugi parametr 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 Selektor kontaktów API można wywoływać tylko z bezpiecznego kontekstu przeglądania najwyższego poziomu. Podobnie jak inne zaawansowane interfejsy API, wymaga on gestu użytkownika.

Wykrywanie dostępnych właściwości

Aby sprawdzić, które usługi są dostępne, wywołaj funkcję navigator.contacts.getProperties(). Zwraca obietnicę, która znika za pomocą tablicy ciągów znaków wskazujących, które właściwości są dostępne. Przykład: ['name', 'email', 'tel', 'address']. Możesz przekazać te wartości do usługi select().

Pamiętaj, że właściwości nie zawsze są dostępne i mogą być dodawane nowe. W przyszłości inne platformy i źródła kontaktów mogą ograniczać udostępnianie usług.

Obsługa wyników

Interfejs API selektora kontaktów zwraca tablicę kontaktów, a każdy kontakt zawiera tablicę żądanych właściwości. Jeśli osoba kontaktowa nie ma danych dotyczących żądanej właściwości lub użytkownik zdecyduje się zrezygnować z udostępniania określonej właściwości, interfejs API zwróci pustą tablicę. (Sposób wybierania właściwości przez użytkownika opisaliśmy w sekcji Kontrola użytkowników).

Jeśli na przykład witryna wysyła żądanie name, email i tel, a użytkownik wybierze 1 kontakt, który ma w polu nazwy dane, poda 2 numery telefonów, ale nie ma adresu e-mail, zwrócona odpowiedź będzie miała postać:

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

Zabezpieczenia i uprawnienia

Zespół Chrome zaprojektował i wdrożył interfejs Contact Picker API zgodnie z podstawowymi zasadami określonymi w artykule Kontrolowanie dostępu do zaawansowanych funkcji platformy internetowej, w tym dotyczących kontroli użytkowników, przejrzystości i ergonomii. Objaśnię każdą z nich.

Kontrola użytkowników

Dostęp do kontaktów użytkownika odbywa się za pomocą selektora. Można je wywoływać tylko gestem użytkownika w bezpiecznym kontekście przeglądania najwyższego poziomu. Dzięki temu witryna nie może wyświetlić selektora podczas wczytywania strony ani losowo wyświetlić go bez żadnego kontekstu.

Zrzut ekranu: użytkownicy mogą wybrać, które usługi chcą udostępnić.
Użytkownicy mogą nie udostępniać niektórych usług. Na tym zrzucie ekranu użytkownik odznaczył przycisk „Numery telefonów”. Witryna prosi o podanie numerów telefonów, ale nie zostanie im udostępniona.

Nie ma możliwości zbiorczego wyboru wszystkich kontaktów, dzięki czemu użytkownicy będą zachęcani do wybierania tylko tych kontaktów, które chcą udostępnić w przypadku danej witryny. Użytkownicy mogą też określać, które usługi mają być udostępniane witrynie, przełączając przycisk usługi w górnej części selektora.

Przejrzystość

Aby ułatwić określenie, które dane kontaktowe są udostępniane, selektor zawsze zawiera nazwę i ikonę kontaktu oraz wszelkie właściwości, o które prosi witryna. Jeśli np. witryna wysyła żądanie name, email i tel, w selektorze będą widoczne wszystkie 3 usługi. Jeśli witryna prosi tylko o tel, w selektorze pojawi się tylko imię i nazwisko oraz numery telefonów.

Zrzut ekranu selektora witryny, która prosi o wszystkie usługi.
Selektor, witryna żądająca name, email i tel, wybrano 1 kontakt.
Zrzut ekranu selektora witryny, w której wymagane są tylko numery telefonów.
Selektor, witryna żądająca tylko opcji tel, wybrano 1 kontakt.
Zrzut ekranu selektora po przytrzymaniu kontaktu.
Rezultatem przytrzymania kontaktu.

Kliknięcie i przytrzymanie kontaktu spowoduje wyświetlenie wszystkich informacji, które zostaną udostępnione po jego wybraniu. (Zobacz zdjęcie kontaktu z kotem Cheshire).

Brak trwałości uprawnień

Dostęp do kontaktów jest możliwy na żądanie i nie jest zachowywane. Za każdym razem, gdy witryna chce uzyskać dostęp, musi wywołać navigator.contacts.select() za pomocą gestu użytkownika, a użytkownik musi indywidualnie 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ą przeglądarki Chrome? A może implementacja różni się od specyfikacji?

  • Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, podaj proste instrukcje odtworzenia błędu i ustaw wartość Komponenty na Blink>Contacts. Usterki to świetny sposób na szybkie i łatwe udostępnianie zadań.

Planujesz korzystać z interfejsu API?

Czy zamierzasz korzystać z interfejsu Contact Picker API? Publiczna pomoc pomaga zespołowi Chrome priorytetowo traktować funkcje, a innym dostawcom przeglądarek pokazuje, jak ważne jest ich wsparcie.

Przydatne linki

Dziękujemy

Wyróżnienie i podziękowania dla Finnura Thorarinssona i Rayana Kanso, którzy wdrażają tę funkcję, oraz Petera Beverloo, którego kod bez wstydu złamałem i refaktoryzowałem do wersji demonstracyjnej.

P.S. W selektorze kontaktów są imiona Alicji z Krainy Czarów.