Средство выбора контактов в Интернете, Средство выбора контактов в Интернете

API выбора контактов предоставляет пользователям простой способ поделиться контактами из своего списка контактов.

Пит ЛеПейдж

Что такое API выбора контактов?

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

Спецификация API выбора контактов, доступная в Chrome 80 на Android M или более поздней версии, представляет собой API по требованию, который позволяет пользователям выбирать записи из своего списка контактов и делиться ограниченными сведениями о выбранных записях с веб-сайтом. Это позволяет пользователям делиться только тем, что они хотят, и тогда, когда они хотят, а также облегчает пользователям связь со своими друзьями и семьей.

Например, веб-клиент электронной почты может использовать API выбора контактов для выбора получателей электронного письма. Приложение голосовой связи по IP может определить, по какому номеру телефона следует позвонить. Или социальная сеть может помочь пользователю узнать, какие друзья уже присоединились.

Использование API выбора контактов

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

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

Чтобы проверить, поддерживается ли API выбора контактов, используйте:

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

Кроме того, на Android для работы средства выбора контактов требуется Android M или более поздняя версия.

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

Точкой входа в 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) {
  // Handle any errors here.
}

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

Обнаружение доступных свойств

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

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

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

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

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

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

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

Команда Chrome разработала и реализовала API выбора контактов, используя основные принципы, определенные в разделе «Управление доступом к мощным функциям веб-платформы» , включая пользовательский контроль, прозрачность и эргономику. Я объясню каждый.

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

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

Снимок экрана: пользователи могут выбирать, какими свойствами делиться.
Пользователи могут отказаться делиться некоторыми свойствами. На этом снимке экрана пользователь снял флажок с кнопки «Телефонные номера». Несмотря на то, что сайт запросил номера телефонов, они не будут переданы сайту.

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

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

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

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

Длительное нажатие на контакт покажет всю информацию, которая будет передана, если контакт выбран. (См. контактное изображение Чеширского кота.)

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

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

Обратная связь

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

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

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

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

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

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

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

Спасибо

Огромный привет и благодарность Финнуру Тораринссону и Райану Кансо, которые реализовали эту функцию, а также Питеру Беверлоо, чей код я бессовестно украл и переработал для демо.

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