Een contactkiezer voor internet

Met de Contact Picker API kunnen gebruikers eenvoudig contacten uit hun contactenlijst delen.

Pete LePage

Wat is de Contact Picker API?

Toegang tot de contacten van de gebruiker op een mobiel apparaat is al sinds (bijna) het begin der tijden een functie van iOS/Android-apps. Het is een van de meest voorkomende functieverzoeken die ik van webontwikkelaars hoor en 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 items uit hun contactenlijst kunnen selecteren en beperkte details van de geselecteerde items met een website kunnen delen. Gebruikers kunnen hiermee alleen delen wat ze willen, wanneer ze willen, en het maakt het voor gebruikers gemakkelijker om contact te leggen met hun vrienden en familie.

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 kan opzoeken welk telefoonnummer gebeld moet worden. Of een sociaal netwerk kan een gebruiker helpen ontdekken welke vrienden zich al hebben aangemeld.

De Contact Picker API gebruiken

De Contact Picker API vereist een methodeaanroep met een options-parameter die de gewenste soorten 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);

Daarnaast vereist de Contact Picker op Android Android M of hoger.

De contactkiezer openen

Het toegangspunt tot de Contact Picker API is navigator.contacts.select() . Wanneer deze wordt aangeroepen, retourneert deze een belofte en wordt de contactkiezer weergegeven, zodat de gebruiker de contactpersonen kan selecteren die hij/zij met de site wil delen. Nadat de gewenste items zijn geselecteerd en op ' Gereed' is geklikt, wordt de belofte omgezet in een reeks door de gebruiker geselecteerde contactpersonen.

Wanneer u select() aanroept, moet u een reeks eigenschappen opgeven die u als eerste parameter wilt retourneren (toegestane waarden zijn 'name' , 'email' , 'tel' , 'address' of 'icon' ). Optioneel kunt u opgeven of er meerdere contactpersonen kunnen worden geselecteerd als tweede parameter.

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 beveiligde browsercontext op het hoogste niveau en vereist, net als andere krachtige API's, een gebaar van de gebruiker.

Beschikbare eigenschappen detecteren

Om te detecteren welke eigenschappen beschikbaar zijn, roept u navigator.contacts.getProperties() aan. Deze retourneert een promise die wordt omgezet in een array met strings die aangeven welke eigenschappen beschikbaar zijn. Bijvoorbeeld: ['name', 'email', 'tel', 'address'] . U kunt deze waarden doorgeven aan select() .

Houd er rekening mee dat accommodaties niet altijd beschikbaar zijn en dat er nieuwe accommodaties kunnen worden toegevoegd. In de toekomst kunnen andere platforms en contactbronnen beperkingen opleggen aan welke accommodaties gedeeld mogen worden.

Omgaan met de resultaten

De Contact Picker API retourneert een array met contacten en elk contact bevat een array met de gevraagde eigenschappen. Als een contact geen gegevens heeft voor de gevraagde eigenschap, of als de gebruiker ervoor kiest om een ​​bepaalde eigenschap niet te delen, retourneert de API een lege array. (Ik beschrijf hoe de gebruiker eigenschappen kiest in het gedeelte Gebruikersinstellingen .)

Als een site bijvoorbeeld name , email en tel . opvraagt, en een gebruiker selecteert één contactpersoon met gegevens in het naamveld, geeft twee telefoonnummers op, maar heeft geen e-mailadres, dan 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 'Toegang tot krachtige webplatformfuncties beheren' , waaronder gebruikerscontrole, transparantie en ergonomie. Ik zal elk principe toelichten.

Gebruikerscontrole

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

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

Er is geen optie om alle contacten in één keer te selecteren. Gebruikers worden daarom aangemoedigd om alleen de contacten te selecteren die ze voor die specifieke website willen delen. Gebruikers kunnen ook bepalen welke objecten met de site worden gedeeld door de objectknop bovenaan de kiezer te gebruiken.

Transparantie

Om duidelijk te maken welke contactgegevens worden gedeeld, toont de kiezer altijd de naam en het pictogram van de contactpersoon, plus eventuele eigenschappen die de site heeft opgevraagd. Als een site bijvoorbeeld name , email en tel opvraagt, worden alle drie de eigenschappen in de kiezer weergegeven. Als een site daarentegen alleen tel opvraagt, toont de kiezer alleen de naam en het telefoonnummer.

Schermafbeelding van de sitekiezer die alle eigenschappen opvraagt.
Picker, site name , email en tel opvraagt, één contactpersoon geselecteerd.
Schermafbeelding van de sitekiezer die alleen telefoonnummers vraagt.
Picker, site vraagt ​​alleen tel , één contactpersoon geselecteerd.
Schermafbeelding van de kiezer wanneer een contactpersoon lang wordt ingedrukt.
Het resultaat van het lang indrukken van een contact.

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

Geen toestemmingspersistentie

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. De gebruiker moet vervolgens individueel de contactpersonen selecteren die hij/zij met de site wil delen.

Feedback

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

Probleem met de implementatie?

Heb je een bug gevonden in de implementatie van Chrome? Of wijkt de implementatie af van de specificatie?

Wilt u de API gebruiken?

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

Nuttige links

Bedankt

Een groot applaus en dank aan Finnur Thorarinsson en Rayan Kanso die de functie implementeren en Peter Beverloo, wiens code ik schaamteloos heb gestolen en gerefactored voor de demo.

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