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

# Что представляет собой 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) — найти, по какому номеру звонить, а в соцсети поможет пользователю найти друзей и знакомых.

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

# Использование 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) {
  // Обработка ошибок.
}

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"]
}]

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

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

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

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

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

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

Чтобы пользователь в точности знал, какие контактные данные передаются, окно выбора всегда отображает имя и значок контакта, а также все свойства, запрошенные сайтом. Например, если сайт запрашивает имя (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 определять приоритет функций и показывает важность их поддержки разработчикам других браузеров.

• Расскажите, как вы планируете использовать API, в обсуждении WICG на Discourse.
• Упомяните в твите @ChromiumDev, поставьте хештег #ContactPicker и расскажите, как вы используете этот API.

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

• Публичное пояснение.
• Спецификация Contact Picker.
• Демонстрация Contact Picker API и ее исходный код.
• Отслеживание ошибок.
• Запись на ChromeStatus.com.
• Компонент Blink: Blink>Contacts.

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

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

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