Телефон на желтом фоне

Окно выбора контактов для веб-страниц

Contact Picker API дает пользователям возможность легко делиться данными из списка контактов.

Published on Updated on

Translated to: English, Português, 한국어, 中文, 日本語

Что представляет собой Contact Picker API

<style> #video-demo { max-height: 600px; } </style>

С давних времен в приложениях для iOS и Android на мобильных устройствах была функция доступа к контактам пользователя. Это одна из самых запрашиваемых разработчиками функций и часто — основная причина, по которой они разрабатывают приложение для iOS или Android.

Contact Picker API реализован в Chrome 80 на Android. Это работающий «по запросу» API, который дает пользователю возможность выбирать записи из списка контактов и передавать ограниченный набор данных из них на веб-сайт. Посетители сами решают, какую информацию и когда передавать. Такая функция упрощает поиск друзей и членов семьи на сайте и общение с ними.

Например, в почтовом веб-клиенте Contact Picker API позволит выбрать получателей письма, в приложении для передачи голоса по IP (VoIP) — найти, по какому номеру звонить, а в соцсети поможет пользователю найти друзей и знакомых.

Caution

Команда Chrome тщательно продумала дизайн и реализацию Contact Picker API, чтобы браузер передавал только те данные, которые выбрал пользователь. См. раздел Безопасность и разрешения ниже.

Текущее состояние

ЭтапСостояние
1. Написание поясненияГотово
2. Создание первоначального проекта спецификацииГотово
3. Сбор отзывов и доработка проектаГотово
4. Испытание в OriginГотово
5. ЗапускChrome 80
Доступно только на Android

Использование Contact Picker API

Для использования Contact Picker API нужно вызывать метод с параметром options, который определяет типы запрашиваемой контактной информации. Второй метод сообщает, какую информацию даст базовая система.

Обнаружение функции

Как проверить, поддерживается ли Contact Picker API:

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

Кроме того, для Contact Picker API требуется Android M или более поздняя версия.

Открытие окна выбора контактов

Точка входа в Contact Picker API — navigator.contacts.select(). При вызове этот метод возвращает промис и показывает окно выбора контактов, в котором пользователь может выбрать контакты для передачи на сайт. После выбора контактов и нажатия на кнопку Готово промис разрешается и дает массив соответствующих контактов.

При вызове select() в качестве первого параметра нужно указать массив свойств, которые должны быть возвращены (допустимые значения: 'name', 'email', 'tel', 'address' и 'icon'). Вторым параметром можно указать, разрешается ли выбрать несколько контактов.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
const contacts = await navigator.contacts.select(props, opts);
handleResults(contacts);
} catch (ex) {
// Обработка ошибок.
}
Caution

Для поддержки 'address' и 'icon' требуется Chrome 84 или более поздняя версия.

Contact Picker API можно вызвать только из безопасного веб-контекста верхнего уровня. Как и другим API с широкими возможностями, ему требуется жест пользователя.

Обнаружение имеющихся свойств

Чтобы узнать, какие свойства есть, вызовите метод navigator.contacts.getProperties(). Он возвращает промис, которое разрешается с массивом строк, указывающих, какие свойства доступны, например: ['name', 'email', 'tel', 'address']. Далее эти значения можно передать в select().

Помните, что некоторые свойства иногда могут быть недоступны. Кроме того, могут добавляться новые. В будущем другие платформы и источники контактов смогут определять, какие свойства можно передавать.

Обработка результатов

Contact Picker API возвращает массив из контактов, каждый из которых содержит массив запрошенных свойств. Если у контакта нет данных для запрошенного свойства или пользователь решает не передавать определенное свойство, API возвращает пустой массив. (Выбор свойств пользователем описывается в разделе Пользовательский контроль.)

Например, если сайт запрашивает имя (name), адрес электронной почты (email) и телефон (tel), а пользователь выбирает один контакт, у которого есть данные в поле name, два номера телефонов, но нет электронной почты, ответ будет следующим:

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

Ярлыки и другие семантические данные в полях контактов отбрасываются.

Безопасность и разрешения

Команда Chrome разработала и внедрила Contact Picker API согласно принципам, определенным в в Контроле доступа к функциям веб-платформы с широкими возможностями, включая пользовательский контроль, прозрачность и удобство. Разъяснение по каждому из этих принципов — ниже.

Пользовательский контроль

Доступ к контактам пользователей осуществляется через окно выбора, которое можно вызвать только жестом пользователя в безопасном веб-контексте верхнего уровня. Благодаря этому сайт не сможет вывести окно выбора при загрузке страницы или случайным образом показать его без какого-либо контекста.

Скриншот. Пользователи могут выбрать, какое свойство передать
Пользователи могут не передавать определенные свойства. На скриншоте пользователь снял выделение с кнопки «Номера телефонов» (Phone numbers), поэтому они не будут переданы, хотя сайт их запрашивал

Выбрать все контакты сразу нельзя — это сделано для того, чтобы поощрять пользователей выбирать только те контакты, которые нужно передать конкретному сайту. Пользователи также определяют, какие свойства передать, — с помощью кнопок свойств в верхней части окна выбора.

Прозрачность

Чтобы пользователь в точности знал, какие контактные данные передаются, окно выбора всегда отображает имя и значок контакта, а также все свойства, запрошенные сайтом. Например, если сайт запрашивает имя (name), адрес электронной почты (email) и телефон (tel), в окне выбора будут показаны все три свойства. А если сайт запрашивает только телефон (tel), то будет показано только имя и номера телефонов.

Скриншот окна выбора для сайта, запрашивающего все свойства
Окно выбора, сайт запрашивает имя (name), адрес электронной почты (email) и телефон (tel), выбран один контакт
Скриншот окна выбора для сайта, запрашивающего только номера телефонов
Окно выбора, сайт запрашивает только телефон (tel), выбран один контакт
Скриншот окна выбора для сайта; долгое нажатие на контакт
Результат долгого нажатия на контакт

При долгом нажатии на контакт отображается вся информация, которая будет передана, если выбрать этот контакт. (См. изображение с контактом «Cheshire Cat».)

Разрешение не сохраняется

Доступ к контактам дается по запросу и не сохраняется. Каждый раз, когда сайту нужен доступ к контактам, он должен вызвать navigator.contacts.select() жестом пользователя, а пользователь должен по одному выбрать контакты для передачи сайту.

Отзывы

Команде Chrome хотелось бы услышать ваши отзывы о работе с Contact Picker API.

Проблема с реализацией?

Нашли ошибку в реализации функции в браузере Chrome? Реализация отличается от спецификации?

  • Сообщите об ошибке на странице https://new.crbug.com. Опишите проблему как можно подробнее, дайте простые инструкции по ее воспроизведению и в поле Components укажите Blink>Contacts. Для демонстрации этапов воспроизведения ошибки удобно использовать Glitch.

Планируете использовать этот API?

Планируете использовать Contact Picker API? Ваш публичный интерес помогает команде Chrome определять приоритет функций и показывает важность их поддержки разработчикам других браузеров.

Полезные ссылки

Благодарности

Большой привет и спасибо Финнуру Тораринссону (Finnur Thorarinsson) и Райану Кансо (Rayan Kanso), которые реализовали эту функцию, а также Питеру Беверлоо (Peter Beverloo), чей код я бессовестно украл и подправил для демонстрации.

P. S. Имена в моем окне выбора контактов — это персонажи из «Алисы в стране чудес».

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.