Un outil de sélection de contacts pour le Web

L'API Contact Picker permet aux utilisateurs de partager facilement des contacts à partir de leur liste de contacts.

Pete LePage

Qu'est-ce que l'API Contact Picker ?

L'accès aux contacts de l'utilisateur sur un appareil mobile est une fonctionnalité des applications iOS/Android depuis (presque) la première fois. C'est l'une des fonctionnalités les plus demandées par les développeurs Web, et c'est souvent la principale raison pour laquelle ils créent une application iOS/Android.

Disponible à partir de Chrome 80 sur Android M ou version ultérieure, les spécifications de l'API Contact Picker sont une API à la demande qui permet aux utilisateurs de sélectionner des entrées dans leur liste de contacts et de partager des détails limités des entrées sélectionnées avec un site Web. Il permet aux utilisateurs de ne partager que ce qu'ils veulent, quand ils le souhaitent, et leur permet de contacter leurs amis et leur famille, et de communiquer avec eux.

Par exemple, un client de messagerie Web peut utiliser l'API Contact Picker pour sélectionner le ou les destinataires d'un e-mail. Une application voix off peut rechercher le numéro de téléphone à appeler. Autre exemple : un réseau social peut aider un utilisateur à découvrir quels amis se sont déjà inscrits.

Utilisation de l'API Contact Picker

L'API Contact Picker nécessite un appel de méthode avec un paramètre d'options qui spécifie les types de coordonnées souhaités. Une deuxième méthode vous indique quelles informations le système sous-jacent fournira.

Détection de fonctionnalités

Pour vérifier si l'API Contact Picker est compatible, utilisez:

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

De plus, sur Android, l'outil de sélection de contacts nécessite Android M ou version ultérieure.

Ouverture du sélecteur de contacts

Le point d'entrée de l'API Contact Picker est navigator.contacts.select(). Lorsqu'il est appelé, il renvoie une promesse et affiche le sélecteur de contacts, ce qui permet à l'utilisateur de sélectionner le ou les contacts qu'il souhaite partager avec le site. Après avoir sélectionné les éléments à partager et cliqué sur Done (OK), la promesse se résout avec un tableau de contacts sélectionnés par l'utilisateur.

Lorsque vous appelez select(), vous devez fournir un tableau des propriétés que vous souhaitez renvoyer en tant que premier paramètre (les valeurs autorisées étant l'une des valeurs suivantes : 'name', 'email', 'tel', 'address' ou 'icon'), et éventuellement indiquer si plusieurs contacts peuvent être sélectionnés en tant que deuxième paramètre.

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.
}

L'API Contacts Picker ne peut être appelée qu'à partir d'un contexte de navigation sécurisé de premier niveau. Comme d'autres API puissantes, elle nécessite un geste de l'utilisateur.

Détecter les propriétés disponibles

Pour détecter les propriétés disponibles, appelez navigator.contacts.getProperties(). Elle renvoie une promesse qui se résout avec un tableau de chaînes indiquant les propriétés disponibles. Exemple : ['name', 'email', 'tel', 'address']. Vous pouvez transmettre ces valeurs à select().

N'oubliez pas que les propriétés ne sont pas toujours disponibles et que de nouvelles propriétés peuvent être ajoutées. À l'avenir, d'autres plates-formes et sources de contact pourront limiter les propriétés partagées.

Gérer les résultats

L'API Contact Picker renvoie un tableau de contacts, et chaque contact inclut un tableau des propriétés demandées. Si un contact ne dispose pas de données pour la propriété demandée ou si l'utilisateur choisit de ne pas partager une propriété particulière, l'API renvoie un tableau vide. (J'ai décrit comment l'utilisateur choisit les propriétés dans la section Commande utilisateur.)

Par exemple, si un site demande les coordonnées name, email et tel, et qu'un utilisateur sélectionne un seul contact dont le champ "name" (nom) contient des données, fournit deux numéros de téléphone, mais n'a pas d'adresse e-mail, la réponse renvoyée est la suivante:

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

Sécurité et autorisations

L'équipe Chrome a conçu et mis en œuvre l'API Contact Picker en suivant les principes fondamentaux définis dans la section Contrôler l'accès aux fonctionnalités puissantes de la plate-forme Web, y compris le contrôle utilisateur, la transparence et l'ergonomie. Je vais vous expliquer chacune d'entre elles.

Contrôle des utilisateurs

L'accès aux contacts des utilisateurs s'effectue via le sélecteur et ne peut être appelé que par un geste de l'utilisateur, dans un contexte de navigation de premier niveau sécurisé. Ainsi, un site ne peut pas afficher le sélecteur au chargement de la page, ni l'afficher de manière aléatoire sans contexte.

Capture d'écran, les utilisateurs peuvent choisir les propriétés qu'ils souhaitent partager.
Les utilisateurs peuvent choisir de ne pas partager certaines propriétés. Dans cette capture d'écran, l'utilisateur a décoché le bouton "Numéros de téléphone". Même si le site a demandé des numéros de téléphone, ceux-ci ne seront pas partagés avec lui.

Il n'existe aucune option permettant de sélectionner tous les contacts de manière groupée afin d'encourager les utilisateurs à ne sélectionner que ceux qu'ils doivent partager pour ce site Web spécifique. Les utilisateurs peuvent également contrôler les propriétés partagées avec le site en cliquant sur le bouton "Propriété" en haut du sélecteur.

Transparence

Pour indiquer clairement les coordonnées partagées, le sélecteur affiche toujours le nom et l'icône du contact, ainsi que toutes les propriétés demandées par le site. Par exemple, si un site demande les propriétés name, email et tel, les trois propriétés s'affichent dans le sélecteur. Si un site ne demande que tel, l'outil de sélection n'affiche que le nom et les numéros de téléphone.

Capture d'écran du sélecteur d'un site demandant toutes les propriétés.
Sélecteur, site demandant name, email et tel, un contact sélectionné.
Capture d'écran du sélecteur d'un site demandant uniquement des numéros de téléphone.
Sélecteur, site demandant uniquement tel, un contact sélectionné.
Capture d'écran du sélecteur lorsque l'utilisateur appuie de manière prolongée sur un contact.
Résultat d'un appui prolongé sur un contact.

Appuyez de manière prolongée sur un contact pour afficher toutes les informations qui seront partagées si le contact est sélectionné. (voir l'image de contact de Cheshire Cat.)

Aucune persistance des autorisations

L'accès aux contacts est à la demande et n'est pas conservé. Chaque fois qu'un site souhaite y accéder, il doit appeler navigator.contacts.select() avec un geste de l'utilisateur, qui doit choisir individuellement le ou les contacts qu'il souhaite partager avec le site.

Commentaires

L'équipe Chrome souhaite connaître votre avis sur votre expérience avec l'API Contact Picker.

Un problème d'implémentation ?

Avez-vous détecté un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente des spécifications ?

  • Signalez un bug à l'adresse https://new.crbug.com. Veillez à inclure autant de détails que possible, à fournir des instructions simples pour reproduire le bug et à définir le champ Composants sur Blink>Contacts. Glitch est idéal pour partager des reproductions de problèmes simples et rapides.

Vous prévoyez d'utiliser l'API ?

Comptez-vous utiliser l'API Contact Picker ? Votre assistance publique aide l'équipe Chrome à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.

Liens utiles

Merci

Merci à Finnur Thorarinsson et Rayan Kanso qui implémentent cette fonctionnalité, ainsi qu'à Peter Beverloo dont le code que j'ai volé et refactorisé sans honte pour la démonstration.

P.S. : Les noms figurant dans mon sélecteur de contacts sont des caractères d'Alice au pays des merveilles.