Note de l'auteur : Les technologies et processus décrits dans cet article sont expérimentaux et ne fonctionneront que dans quelques navigateurs. Au moment de la rédaction de cet article, l'API Contact Picker n'était prise en charge que par Android Chrome (à partir de la version 80) et iOS Safari (à partir de la version 14.5, mais uniquement derrière un drapeau). Si vous souhaitez revoir la fonctionnalité, vous pouvez consulter une démo en cours sur mon site Web.

---

La lecture des entrées de la liste de contacts sur un téléphone ou une tablette est traditionnellement limitée aux applications natives. Mais avec l'API Contact Picker, c'est exactement ce que nous pouvons faire en utilisant JavaScript.

Cette fonctionnalité peut être intéressante dans les applications qui nécessitent des informations de contact comme les numéros de téléphone ou la VoIP, les réseaux sociaux où l'on souhaite découvrir des personnes connues, ou les applications qui nécessitent de remplir des informations de formulaire sans changer d'application pour afficher les données.

L'API et l'appareil limiteront les propriétés qui seront disponibles. Il existe cinq standards que les développeurs peuvent sélectionner :

• Noms
• Téléphones
• E-mails
• Adresses
• Icônes

Les pluriels ici sont importants, car un contact peut avoir plusieurs téléphones, e-mails ou plusieurs adresses. Les données renvoyées seront toujours dans des tableaux pour des raisons de cohérence, même s'il s'agit d'une valeur unique. Nous en reparlerons plus tard.

---

Confidentialité et sécurité

Les informations de contact stockées sur un téléphone peuvent contenir des informations sensibles que nous devons traiter avec attention. Pour cette raison, nous devons prendre en compte des considérations en matière de confidentialité et de sécurité :

• Le code de l'API Contact Picker doit s'exécuter dans le contexte de navigation de niveau supérieur. Il empêche le code externe, comme les publicités ou les plugins tiers, de lire la liste de contacts sur votre téléphone.
• Le code de l'API Contact Picker ne peut s'exécuter qu'après un geste de l'utilisateur. Ainsi, les développeurs ne peuvent pas automatiser entièrement le processus. L'utilisateur doit agir pour déclencher la lecture du contact.
• La personne doit autoriser l'accès à la liste de contacts. Cette restriction est imposée par le téléphone et non par JS. L'utilisateur doit accorder au navigateur l'autorisation d'accéder aux contacts (s'il ne l'a pas déjà).

La première fois qu'ils utilisent un site Web qui utilise l'API Contact Picker, ils peuvent recevoir un message comme celui-ci :

Le téléphone affichera cette fenêtre contextuelle à chaque fois jusqu'à ce que l'utilisateur appuie sur « Autoriser ». L'API Contact Picker ne s'exécutera pas tant que cela ne se produira pas. Ce qui est bien ; nous voulons nous assurer que les utilisateurs accordent les autorisations appropriées. C'est aussi bien que ce soit une chose ponctuelle ; accorder une autorisation à chaque fois que la page exécute le code de l'API Contact Picker serait une douleur dans le cou.

---

L'API et le code

L'API Contact Picker ne définit que deux méthodes :

• getProperties() : renvoie une liste des propriétés disponibles en lecture sur l'appareil. Dans la définition, il n'y en a que cinq : « adresse », « email », « icône » (il ne s'agit peut-être pas de la photo du contact), « nom », « tel » (téléphone), mais l'appareil peut ne pas autoriser l'accès à tous. d'entre eux.
• select() : ouvre la fenêtre contextuelle de contact et renvoie la sélection une fois que l'utilisateur a terminé l'action. Il prend deux paramètres : une liste des propriétés à lire et un objet optionnel avec des options.

Les deux méthodes renvoient des promesses, mais étant donné que les actions qu'elles déclenchent bloquent le flux régulier de l'application, nous devons utiliser async / wait lors de leur gestion.

Il peut être tentant d'ignorer getProperties() et de demander directement toutes les propriétés. Mais attention si vous faites cela : cela fonctionnera probablement, mais si l'une des propriétés spécifiées n'est pas disponible, la méthode select() lèvera une exception.

Exemple

Une démo de l'API Contact Picker est en action (exécutez-la en ligne ici ou regardez cette vidéo). Si l'API est prise en charge, elle affiche un bouton qui lit le numéro de téléphone, le nom et l'adresse e-mail du contact pour l'afficher.

Tout d’abord, nous avons besoin du bouton. Comme détaillé précédemment dans la section Confidentialité et sécurité, une action de l'utilisateur est requise avant que nous puissions appeler l'API, nous ne pouvons donc rien déclencher sans interaction de l'utilisateur :

Show contact data

Le code principal sera dans la fonction getContactData(). Mais avant cela, quel serait l’intérêt d’afficher le bouton si l’API Contact Picker n’est pas disponible ? Masquons le bouton s'il n'est pas disponible. Ou encore mieux, masquons le bouton par défaut (en ajoutant l'attribut caché) et ne l'affichons que si l'API est disponible.

// only show the button if browser supports Contact Picker API
if ("contacts" in navigator) {
  document.querySelector("button").removeAttribute("hidden");
}

Maintenant que la logique des boutons est en place, concentrons-nous sur getContactData(). Voici une version commentée de la fonction :

// it is asynchronous because we'll wait for the modal selection
async function getContactData() {
  // indicate what contact values will be read
  const props = ["tel", "name", "email"];

  // wrap everything in a try...catch, just in case
  try {
    // open the native contact selector (after permission is granted)
    const contacts = await navigator.contacts.select(props);

    // this will execute after the native contact selector is closed
    if (contacts.length) {
      // if there's data, show it
      alert("Selected data: "   JSON.stringify(contacts));
    } else {
      // ...if not, indicate nothing was selected
      alert("No selection done");
    }
  } catch (ex) {
    // if something fails, show the error message
    alert(ex.message)
  }
}

Une fois que le bouton déclenche cette fonction, et si le navigateur dispose des autorisations (voir capture d'écran dans la section précédente), le modal de contact apparaîtra, indiquant les informations essentielles : l'URL lisant les données, quelles données il renverra et le liste de contacts parmi lesquels choisir.

Après la fermeture du modal, la variable contacts stockera les données en JSON sous forme de tableau avec un objet contenant les informations demandées (il peut être vide s'il n'est pas disponible dans la fiche de contact).

Par exemple, voici le résultat après m'être sélectionné comme contact (fausses données) :

[
  {
    "address": [],
    "email": [ "[email protected]" ],
    "icon": [],
    "name": [ "Alvaro Montoro" ],
    "tel": [ "555-555-5555", "555-123-4567" ]
  }
]

, "icône": [], "nom":

, "tél":

} ]

Si les données incluent une icône, ce sera un blob avec l'image. Si les données incluent une adresse, il s'agira d'un objet plus complexe avec la rue, la ville, le pays, le code postal, etc. Vous pouvez vérifier les valeurs renvoyées dans la spécification.

Mais pourquoi un tableau si on n'a sélectionné qu'un seul contact ? Parce qu'il existe la possibilité de choisir plusieurs contacts !

Sélection de plusieurs contacts

const props = ["tel", "address", "icon", "name", "email"];
// only one option available: read multiple or only one (default)
const options = { multiple: true };

try {
  const contacts = await navigator.contacts.select(props, options);
  // ...

Il est possible de sélectionner plusieurs contacts. Si nous voulons faire cela, nous devons passer un deuxième paramètre à la méthode navigator.contacts.select() indiquant cette option.

const props = ["tel", "adresse", "icône", "nom", "e-mail"]; // une seule option disponible : lire plusieurs ou une seule (par défaut) options const = { multiple : vrai } ; essayer { const contacts = wait navigator.contacts.select(props, options); //...

---

Le résultat est un tableau de contacts, donc le reste du code pourrait rester le même pour cet exemple.

const props = ["tel", "address", "icon", "name", "email"];
// only one option available: read multiple or only one (default)
const options = { multiple: true };

try {
  const contacts = await navigator.contacts.select(props, options);
  // ...

Le code ci-dessus peut être intimidant, principalement à cause de tous les commentaires que j'ai ajoutés. Voici une version légèrement commentée du code ci-dessus. Comme vous l'avez peut-être remarqué, c'est assez simple :

fonction asynchrone getContactData() { if ("contacts" dans le navigateur) { const props = attendre navigator.contacts.getProperties(); options const = { multiple : vrai } ; essayer { const contacts = wait navigator.contacts.select(props, options); si (contacts.longueur) { // code gérant les données sélectionnées } autre { // code quand rien n'a été sélectionné } } attraper (ex) { // code s'il y a eu une erreur } } }

---

Vous pouvez consulter une démo en cours sur mon site Web

. Ne vous inquiétez pas, je ne fais rien avec les informations de contact, à part les écrire sur l'écran. Mais relisez le code avant si vous ne me faites pas confiance.

Conclusion : la confidentialité plutôt que le piratage

Les informations de contact sont des PII (Personally Identifiable Information) et nous devons les traiter avec tout le soin et la sécurité que nécessitent les données sensibles.

• Outre d'éventuelles exigences légales que je ne vais pas respecter (car je ne les connais pas et qu'elles changent d'un pays à l'autre), voici quelques directives de base concernant le traitement de données sensibles :
Respectez la vie privée des gens. Ne les forcez pas à partager des informations qu'ils ne souhaitent pas partager.
Traitez les données avec soin et en toute sécurité. Seriez-vous à l'aise si les données que vous traitez étaient les vôtres ?
Ne stockez pas de données si vous n'en avez pas besoin. Lisez-le, utilisez-le, oubliez-le. Ne stockez pas les données que vous n'utilisez pas.

Obtenez uniquement les données dont vous avez besoin. Ne soyez pas sournois ou louche. Obtenez exactement ce dont vous avez besoin pour renforcer votre crédibilité et votre confiance.

Supposons qu'une application Web tente de lire des adresses, des noms ou des e-mails tout en sélectionnant un numéro de téléphone. Si cela m'arrivait, je rejetterais automatiquement l'autorisation et quitterais le site Web.

---

---

Alors, explorez JavaScript et l'API Contact Picker, mais rappelez-vous toujours qu'il y a une personne derrière l'écran et que les données qu'elle partage peuvent être risquées si elles tombent entre de mauvaises mains. Ne soyez pas imprudent.

Si vous avez apprécié cet article sur JavaScript et que vous aimez tester les API Web et différentes choses avec JS, consultez cet autre article :

Développer un jeu Rock Band avec HTML et JavaScript