Selektor kontaktów w internecie

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

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

Wykrywam dostępne właściwości

Aby wykryć, 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 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.

Praca z wynikami

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, emailtel, 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 dzięki selektorowi, który można wywołać 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świetlać selektora bez żadnego kontekstu.

Zrzut ekranu; użytkownicy mogą wybrać, które właściwości 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ł przycisk „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, emailtel, 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 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? 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, 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 podziw dla Finnur Thorarinssona i Rayana Kanso, którzy wdrożyli tę funkcję, oraz Petera Beverloo, którego kod bez trudu skradziłem i zoptymalizowałem na potrzeby wersji demonstracyjnej.

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