Un outil de sélection de contacts pour le Web

L'API Contact Picker permet aux utilisateurs de partager facilement des contacts depuis 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 nuit des temps. C'est l'une des demandes de fonctionnalités les plus courantes que j'entends de la part des développeurs Web, et c'est souvent la raison principale pour laquelle ils créent une application iOS/Android.

Disponible à partir de Chrome 80 sur Android M ou version ultérieure, la spécification de l'API Contact Picker est une API à la demande qui permet aux utilisateurs de sélectionner des entrées dans leur liste de contacts et de partager des informations limitées sur les entrées sélectionnées avec un site Web. Elle permet aux utilisateurs de partager uniquement ce qu'ils souhaitent, quand ils le souhaitent, et leur permet de contacter plus facilement leurs amis et leur famille.

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 de voix sur IP pourrait rechercher le numéro de téléphone à appeler. Un réseau social peut également aider un utilisateur à découvrir quels amis ont déjà rejoint le service.

Utiliser 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 d'informations de contact que vous souhaitez. Une deuxième méthode vous indique les informations que le système sous-jacent fournira.

Détection de caractéristiques

Pour vérifier si l'API Contact Picker est prise en charge, utilisez :

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

De plus, sur Android, le sélecteur de contacts nécessite Android M ou une version ultérieure.

Ouvrir le sélecteur de contacts

Le point d'entrée de l'API Contact Picker est navigator.contacts.select(). Lorsqu'elle est appelée, elle 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 OK, la promesse est résolue avec un tableau de contacts sélectionnés par l'utilisateur.

Lorsque vous appelez select(), vous devez fournir un tableau de propriétés que vous souhaitez renvoyer en tant que premier paramètre (avec 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 de premier niveau sécurisé. 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 peuvent être ajoutées. À l'avenir, d'autres plates-formes et sources de contacts pourront limiter les propriétés qui peuvent être 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é spécifique, l'API renvoie un tableau vide. (Je décris comment l'utilisateur choisit les propriétés dans la section Contrôle utilisateur.)

Par exemple, si un site demande name, email et tel, et qu'un utilisateur sélectionne un seul contact dont le champ "Nom" est renseigné, fournit deux numéros de téléphone, mais n'a pas d'adresse e-mail, la réponse renvoyée sera 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 implémenté l'API Contact Picker en utilisant les principes de base définis dans Controlling Access to Powerful Web Platform Features, y compris le contrôle utilisateur, la transparence et l'ergonomie. Je vais vous les expliquer.

Contrôle des utilisateurs

L'accès aux contacts des utilisateurs se fait via le sélecteur, qui ne peut être appelé qu'avec un geste de l'utilisateur, dans un contexte de navigation sécurisé de premier niveau. Cela permet de s'assurer qu'un site ne peut pas afficher le sélecteur au chargement de la page ni l'afficher de manière aléatoire sans aucun contexte.

Capture d'écran montrant que les utilisateurs peuvent choisir les propriétés à 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, ils ne seront pas partagés avec lui.

Il n'est pas possible de sélectionner tous les contacts à la fois. Les utilisateurs sont ainsi encouragés à ne sélectionner que les contacts qu'ils doivent partager pour un site Web donné. Les utilisateurs peuvent également contrôler les propriétés partagées avec le site en activant ou désactivant le bouton des propriétés 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 name, email et tel, les trois propriétés s'affichent dans le sélecteur. Sinon, si un site ne demande que tel, le sélecteur n'affichera que le nom et les numéros de téléphone.

Capture d'écran du sélecteur pour 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 pour 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 lorsqu'un contact est appuyé de manière prolongée.
Résultat d'un appui prolongé sur un contact.

Si vous appuyez de manière prolongée sur un contact, toutes les informations qui seront partagées si le contact est sélectionné s'affichent. (Voir l'image de contact du Chat du Cheshire.)

Aucune persistance des autorisations

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

Commentaires

L'équipe Chrome aimerait connaître votre avis sur l'API Contact Picker.

Vous rencontrez un problème d'implémentation ?

Avez-vous trouvé un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente de la spécification ?

Vous prévoyez d'utiliser l'API ?

Comptez-vous utiliser l'API Contact Picker ? Votre soutien public 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

Un grand merci à Finnur Thorarinsson et Rayan Kanso qui implémentent la fonctionnalité, ainsi qu'à Peter Beverloo dont j'ai volé sans vergogne le code et que j'ai refactorisé pour la démo.

PS : Les noms dans mon sélecteur de contacts sont des personnages d'Alice au pays des merveilles.