Interfejs Contact Picker API umożliwia użytkownikom łatwe udostępnianie kontaktów z ich listy kontaktów.
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 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
, 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 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.
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.
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.
- W wątku na forum Discourse dotyczącej WGICh opisz, jak zamierzasz go używać.
- Wyślij tweeta na adres @ChromiumDev, używając hashtagu
#ContactPicker
, i daj nam znać, gdzie i jak go używasz.
Przydatne linki
- Publiczny film wyjaśniający
- Specyfikacja selektora kontaktów
- Demak Contact Picker API i źródło dema Contact Picker API
- Śledzenie błędu
- Wpis na stronie ChromeStatus.com
- Komponent Blink:
Blink>Contacts
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”.