Een contactkiezer voor internet

De Contact Picker API biedt gebruikers een eenvoudige manier om contacten uit hun contactenlijst te delen.

Piet LePage

Wat is de Contactkiezer-API?

Toegang tot de contacten van de gebruiker op een mobiel apparaat is al sinds (bijna) het begin der tijden een kenmerk van iOS/Android-apps. Het is een van de meest voorkomende functieverzoeken die ik hoor van webontwikkelaars, en is vaak de belangrijkste reden waarom ze een iOS/Android-app bouwen.

De Contact Picker API-specificatie, beschikbaar vanaf Chrome 80 op Android M of hoger, is een on-demand API waarmee gebruikers vermeldingen uit hun contactenlijst kunnen selecteren en beperkte details van de geselecteerde vermeldingen kunnen delen met een website. Het stelt gebruikers in staat alleen te delen wat ze willen, wanneer ze maar willen, en maakt het gemakkelijker voor gebruikers om hun vrienden en familie te bereiken en ermee in contact te komen.

Een webgebaseerde e-mailclient kan bijvoorbeeld de Contact Picker API gebruiken om de ontvanger(s) van een e-mail te selecteren. Een voice-over-IP-app zou kunnen opzoeken welk telefoonnummer je moet bellen. Of een sociaal netwerk kan een gebruiker helpen ontdekken welke vrienden zich al hebben aangemeld.

Met behulp van de Contactkiezer-API

De Contact Picker API vereist een methodeaanroep met een optieparameter die de gewenste typen contactgegevens specificeert. Een tweede methode vertelt u welke informatie het onderliggende systeem zal verstrekken.

Functiedetectie

Om te controleren of de Contact Picker API wordt ondersteund, gebruikt u:

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

Bovendien vereist de Contactkiezer op Android Android M of hoger.

De contactkiezer openen

Het toegangspunt tot de Contact Picker API is navigator.contacts.select() . Wanneer hij wordt gebeld, wordt er een belofte teruggestuurd en wordt de contactkiezer weergegeven, zodat de gebruiker de contact(en) kan selecteren die hij met de site wil delen. Nadat u hebt geselecteerd wat u wilt delen en op Gereed hebt geklikt, wordt de belofte opgelost met een reeks contacten die door de gebruiker zijn geselecteerd.

Wanneer u select() aanroept, moet u een reeks eigenschappen opgeven die u als eerste parameter wilt retourneren (waarbij de toegestane waarden 'name' , 'email' , 'tel' , 'address' of 'icon' zijn) en optioneel of meerdere contacten als tweede parameter kunnen worden geselecteerd.

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

De Contacts Picker API kan alleen worden aangeroepen vanuit een veilige browsercontext op het hoogste niveau, en vereist, net als andere krachtige API's, een gebruikersgebaar.

Het detecteren van beschikbare eigendommen

Om te detecteren welke eigenschappen beschikbaar zijn, roept u navigator.contacts.getProperties() aan. Het retourneert een belofte die wordt opgelost met een reeks tekenreeksen die aangeven welke eigenschappen beschikbaar zijn. Bijvoorbeeld: ['name', 'email', 'tel', 'address'] . U kunt deze waarden doorgeven aan select() .

Houd er rekening mee dat eigendommen niet altijd beschikbaar zijn en dat er nieuwe eigendommen kunnen worden toegevoegd. In de toekomst kunnen andere platforms en contactbronnen beperken welke eigendommen worden gedeeld.

Het verwerken van de resultaten

De Contact Picker API retourneert een reeks contacten, en elke contactpersoon bevat een reeks van de gevraagde eigenschappen. Als een contactpersoon geen gegevens heeft voor de gevraagde eigenschap, of als de gebruiker ervoor kiest om het delen van een bepaalde eigenschap uit te schakelen, retourneert de API een lege array. (Ik beschrijf hoe de gebruiker eigenschappen kiest in de sectie Gebruikersbeheer .)

Als een site bijvoorbeeld vraagt ​​om name , email en tel , en een gebruiker selecteert één contactpersoon die gegevens in het naamveld heeft, twee telefoonnummers opgeeft, maar geen e-mailadres heeft, is het geretourneerde antwoord:

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

Beveiliging en machtigingen

Het Chrome-team heeft de Contact Picker API ontworpen en geïmplementeerd met behulp van de kernprincipes die zijn gedefinieerd in Toegangscontrole tot krachtige webplatformfuncties , waaronder gebruikerscontrole, transparantie en ergonomie. Ik zal ze allemaal uitleggen.

Gebruikerscontrole

Toegang tot de contacten van de gebruikers verloopt via de kiezer en kan alleen worden gebeld met een gebruikersgebaar, in een veilige browsercontext op het hoogste niveau. Dit zorgt ervoor dat een site de kiezer niet kan weergeven bij het laden van de pagina, of de kiezer willekeurig kan weergeven zonder enige context.

Schermafbeelding, gebruikers kunnen kiezen welke eigendommen ze willen delen.
Gebruikers kunnen ervoor kiezen sommige eigenschappen niet te delen. In deze schermafbeelding heeft de gebruiker de knop 'Telefoonnummers' uitgeschakeld. Hoewel de site om telefoonnummers vraagt, worden deze niet met de site gedeeld.

Er is geen optie om alle contacten in bulk te selecteren, zodat gebruikers worden aangemoedigd alleen de contacten te selecteren die ze voor die specifieke website moeten delen. Gebruikers kunnen ook bepalen welke eigenschappen met de site worden gedeeld door op de eigenschappenknop bovenaan de kiezer te klikken.

Transparantie

Om duidelijk te maken welke contactgegevens worden gedeeld, toont de kiezer altijd de naam en het pictogram van de contactpersoon, plus eventuele eigendommen die de site heeft aangevraagd. Als een site bijvoorbeeld vraagt ​​om name , email en tel , worden alle drie de eigenschappen in de kiezer weergegeven. Als een site alleen tel vraagt, toont de kiezer alleen de naam en telefoonnummers.

Schermafbeelding van de kiezer voor de site die alle eigendommen opvraagt.
Kiezen, name , email en tel ., één contactpersoon geselecteerd.
Schermafbeelding van de kiezer voor een site die alleen telefoonnummers opvraagt.
Picker, site vraagt ​​alleen tel ., één contactpersoon geselecteerd.
Schermafbeelding van de kiezer wanneer een contact lang wordt ingedrukt.
Het resultaat van lang drukken op een contact.

Als u lang op een contact drukt, wordt alle informatie weergegeven die wordt gedeeld als het contact is geselecteerd. (Zie de contactafbeelding van de Cheshire Cat.)

Geen persistentie van toestemming

Toegang tot contacten is op aanvraag en niet permanent. Elke keer dat een site toegang wil, moet deze navigator.contacts.select() aanroepen met een gebruikersgebaar, en moet de gebruiker individueel de contact(en) kiezen die hij/zij met de site wil delen.

Feedback

Het Chrome-team wil graag horen wat uw ervaringen zijn met de Contact Picker API.

Probleem met de implementatie?

Heeft u een bug gevonden in de implementatie van Chrome? Of wijkt de uitvoering af van de specificaties?

  • Dien een bug in op https://new.crbug.com . Zorg ervoor dat u zoveel mogelijk details vermeldt, geef eenvoudige instructies voor het reproduceren van de bug en stel Componenten in op Blink>Contacts . Glitch werkt prima voor het delen van snelle en gemakkelijke probleemreproducties.

Bent u van plan de API te gebruiken?

Bent u van plan de Contact Picker API te gebruiken? Uw publieke steun helpt het Chrome-team prioriteiten te stellen voor functies en laat andere browserleveranciers zien hoe belangrijk het is om deze te ondersteunen.

Handige Links

Bedankt

Grote schreeuw en dank aan Finnur Thorarinsson en Rayan Kanso die de functie implementeren en Peter Beverloo wiens code ik schaamteloos heb gestolen en opnieuw heb bewerkt voor de demo.

PS: De namen in mijn contactkiezer zijn personages uit Alice in Wonderland.