Contact Picker API позволяет предоставить сайту доступ к выбранным пользователем контактам из его записной книжки. В данной заметке мы разберём возможности, которые у нас появились, и некоторые, возможно, неочевидные моменты.
Что это и зачем?
Представьте: вы хотите пригласить своего друга на ваш любимый сайт; оформляете интернет-заказ и хотите указать контактный номер жены как получателя; вызываете такси для коллеги и указываете его номер как номер пассажира (да, я понимаю, что самый популярный кейс тут первый, но с остальными я также столкнулся за последний месяц) или ещё как-то и где-то указываете номер телефона из своей записной книжки. Что вы делаете? Сворачиваете браузер или приложение, открываете приложение «Телефон», откуда переходите в «Контакты», ищете нужную запись, заходите в неё, копируете номер, снова открываете браузер или приложение, выбираете поле для ввода, вставляете скопированную запись. Квест выполнен!
Contact Picker API позволяет пользователю достичь той же цели значительно быстрее: нажать на кнопку, найти нужную запись, выбрать её, нажать «Готово». Круто? Да. Сложно для реализации? Нет.
Где и как это работает?
В Android 6+ и Chrome 80+, а также за флагом в iOS 14.5 beta 2. Вы можете попробовать API в демо от разработчиков.
API
API включает в себя класс ContactsManager и инстанс этого класса по ссылке window.navigator.contacts.
Имеются два асинхронных метода: getProperties, позволяющий узнать, какого рода информацию о контактах вообще может предоставить текущая связка браузера и операционной системы, и select, как раз отображающий пользователю запрос на выбор данных из записной книжки.
В текущий момент черновик предложения спецификации говорит, что через API можно получить следующие типы полей: «address», «email», «icon», «name» и «tel». То есть прежде, чем просить пользователя поделиться информацией, скажем, о почте и изображении пользователя, хорошо было бы проверить, есть ли у пользователя такая возможность.
const supportedProps = await navigator.contacts.getProperties();
if (supportedProps.includes('address') && supportedProps.includes('icon')) {
// всё хорошо, показываем волшебную кнопку для выбора контактов
}После этого мы можем с чистой совестью попросить пользователя выбрать контакт или контакты.
Метод navigator.contacts.select первым аргументом принимает обязательный массив типов полей, которые нам нужны. Эта информация будет использована операционной системой для уведомления пользователя о том, чем именно он поделится. Те поля, которые вы не запросили явно, вы не получите. Вторым, опциональным аргументом можно передать объект дополнительных настроек. Сейчас это только multiple (по умолчанию false), т.е. один контакт можно будет выбрать пользователю, либо несколько.
В результате вызова вы получите массив (всегда, вне зависимости от значения multiple) объектов-описаний контактов, где ключами будут запрошенные типы полей, а значениями — массивы их значений (всегда — массивы). Пример:
[{
"email": [],
"name": ["Queen O’Hearts"],
"tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]Поля «email», «name» и «tel» являются массивами строк. Для почты и телефона это логично. А вот если заполнить все поля, относящиеся к имени, которые предоставляет Android, то в качестве значения имени всё равно будет получен массив из лишь одной строки формата <обращение> <имя> <отчество> <фамилия>, <звание/титул>. Поле «address» приходит как массив объектов, соответствующих интерфейсу ContactAddress, расширяющему (но ничего не добавляющему) интерфейс PaymentAddress. Поле «icon» — как массив Blob-ов.
Теперь мы можем использовать эту информацию по своему усмотрению.
Что может пойти не так
Как можно было заметить выше, нам всегда приходят массивы значений. Это потому, что у контакта может быть записано как несколько номеров телефонов, так и ни одного. Это всегда нужно будет проверять и предусматривать в дизайне перед дальнейшим использованием.
Что ещё может пойти не так? Пользователь банально может нажать кнопку «Назад», не выбрав контакты. При этом результат вызова всё равно будет успешным и вы получите пустой массив.
В случае, если у приложения нет доступа к списку контактов (запрет на уровне системы), либо операционная система не поддерживает данную возможность, вы получите TypeError: Unable to open a contact selector.
Определение поддержки
Авторы рекомендуют проверять наличие поддержки таким образом:
const supported = ('contacts' in navigator && 'ContactsManager' in window);Но дополнительно, возможно, стоит проверить, а не Android 5- ли сейчас перед вами. Сделать это можно по юзерагенту. Если процент пользователей этих версий мал, можно ограничиться общим отловом ошибок вида Unable to open a contact selector.
Безопасность и предоставление доступа
При первом обращении к этому API, если браузеру не был предоставлен доступ к контактам ранее, система запросит доступ для приложения браузера. В случае разрешения в последующие разы никаких дополнительных запросов не будет. Обратите внимание, что это совсем не похоже на привычную схему получения доступа сайтов к специфичным API. Если обычно мы делаем запрос для текущего ориджина, то есть можем запретить и разрешить доступ, например, к камере, индивидуально для каждого сайта, то тут вы автоматически делаете запрос для всего приложения, никаких дополнительных индивидуальных запросов на каждый ориджин вы делать не будете. А соответственно, вы не можете узнать статус разрешения данного API через Permission API, в любом случае придётся пробовать и обрабатывать исключения.
Почему это хорошо и правильно в данном случае? Несколько причин. Первая: для вызова метода navigator.contacts.select необходимо явное действие пользователя, вызвать программно, например, сразу после загрузки страницы не получится. Вторая: интерфейс выбора пользователя, судя по всему, относится именно к самой ОС, и у скриптов сайтов нет никакой возможности вмешаться в выбор пользователя. А значит, нет никакого шанса получить список контактов пользователя без его спроса. Каждый раз, когда пользователь наткнётся на интерфейс выбора контактов, это будет следствием его явного действия, и ему первым делом будет выдано пояснение, какой именно сайт и какую именно информацию получит, если пользователь решит продолжить.
Особенности дизайна
Что нужно предусмотреть:
- наличие поддержки API;
- возможные ошибки, связанные с доступом к контактам или поддержкой со стороны ОС;
- вариант, когда пользователь передумает и не выберет контакты;
- вариант, когда желаемых данных у контакта не будет или наоборот, будет несколько (к примеру, два телефона или три почты).
Поддержка API в Chrome на других операционных системах
В настоящий момент данное API доступно только на Android. Потенциально в будущем оно может быть доступно и на других ОС, например, в Windows 10 для реализации Contact Picker API есть подходящее API Windows.ApplicationModel.Contacts, а в macOS — API Contacts. Но на данный момент никаких заявлений от разработчиков Chrome по поводу поддержки других ОС я не встречал.
Другие браузеры
Скорее всего все Chroimum-based-браузеры на Android автоматически получат это API после обновления движка до определённой версии, хоть это и не точно. Лично у меня пока есть небольшие сомнения насчёт браузеров Samsung Internet и Miui, они иногда имеют некоторые особенности.
Firefox пока не определился по поводу своей официальной позиции относительно этого API, но на настоящий момент отношение положительное. UPD: Firefox принял решение не реализовывать данное API в ближайшее время.
Ожидать какой-то реакции или, тем более, поддержки со стороны Safari не стоит, тем более что некая аналогичная базовая функциональность там уже есть, и реализована она просто как автозаполнение полей форм. Вот демо для вашего Safari. UPD: Внезапно, данное API без объявления войны было имплементировано за флагом в iOS 14.5 beta 2 и уже находится во вполне работоспособном состоянии. Когда фича будет доступна всем пользователям спрогнозировать сложно, остаётся только ждать. Работает API в самом Safari и в режиме рабочего стола, в альтернативных браузерах — не доступно. В десктопном Safari Technology Preview тоже имеется такой флаг, но попытка его использовать приводит к исключению.
Заключение
Данное API — ещё один шаг Проекта Фугу по направлению к сокращению разрыва между вебом и нативными приложениями. Разумеется, не получится написать альтернативное приложение для управления контактами, но большинство сценариев использования, как мне кажется, оно покрывает и делает вашего пользователя немного счастливее. Напишите свои мысли по этому поводу или поделитесь возможными сценариями использования!