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 kontaktowanie się z rodziną i znajomymi.

Na przykład klient poczty e-mail działający w przeglądarce może użyć interfejsu Contact Picker API do wybrania 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 options, który określa pożądane 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, dzięki któremu użytkownik może wybrać kontakty, które chce 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 wykryć, które właściwości są dostępne, wywołaj navigator.contacts.getProperties(). Zwraca obietnicę, która zwraca tablicę ciągów znaków wskazującą, 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 usługi nie zawsze są dostępne, a nowe mogą być dodawane. 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 może wyświetlić selektora podczas wczytywania strony ani losowo wyświetlać selektora bez żadnego kontekstu.

Zrzut ekranu pokazujący, jak użytkownicy mogą wybrać usługi, które chcą udostępnić.
Użytkownicy mogą zdecydować, że nie będą udostępniać niektórych właściwości. 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, jeden kontakt wybrany.
Zrzut ekranu selektora w witrynie, która prosi tylko o numery telefonów
Picker, strona prosząca tylko o tel, jeden kontakt wybrany.
Zrzut ekranu z okna selektora po przytrzymaniu kontaktu.
Wynik przytrzymania kontaktu.

Długie naciśnięcie kontaktu spowoduje wyświetlenie wszystkich informacji, które zostaną udostępnione, jeśli kontakt zostanie wybrany. (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ć Twoje wrażenia z korzystania z interfejsu Contact Picker API.

Problem z implementacją?

Czy znalazłeś/znalazłaś błąd w implementacji Chrome? Czy implementacja różni się od specyfikacji?

  • Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, dołącz proste instrukcje odtwarzania błędu i ustaw wartość Components 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.

PS: nazwy w moim selektorze kontaktów to postacie z „Alicji w Krainie Czarów”.