Un selettore di contatti per il Web

L'API Contact Picker offre agli utenti un modo semplice per condividere i contatti dal proprio elenco di contatti.

Pete LePage

Che cos'è l'API Contact Picker?

L'accesso ai contatti dell'utente su un dispositivo mobile è una funzionalità delle app iOS/Android fin (quasi) dalla notte dei tempi. È una delle richieste di funzionalità più comuni che ricevo dagli sviluppatori web ed è spesso il motivo principale per cui creano un'app per iOS/Android.

Disponibile da Chrome 80 su Android M o versioni successive, la specifica dell'API Contact Picker è un'API on demand che consente agli utenti di selezionare voci dal proprio elenco di contatti e condividere dettagli limitati delle voci selezionate con un sito web. Consente agli utenti di condividere solo ciò che vogliono, quando vogliono, e semplifica il modo in cui gli utenti possono raggiungere e connettersi con amici e familiari.

Ad esempio, un client di posta basato sul web potrebbe utilizzare l'API Contact Picker per selezionare i destinatari di un'email. Un'app VoIP potrebbe cercare il numero di telefono da chiamare. Oppure un social network potrebbe aiutare un utente a scoprire quali amici hanno già aderito.

Utilizzo dell'API Contact Picker

L'API Contact Picker richiede una chiamata al metodo con un parametro options che specifica i tipi di dati di contatto che vuoi. Un secondo metodo ti indica quali informazioni fornirà il sistema sottostante.

Rilevamento delle funzionalità

Per verificare se l'API Contact Picker è supportata, utilizza:

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

Inoltre, su Android, il selettore di contatti richiede Android M o versioni successive.

Aprire il selettore contatti

Il punto di ingresso dell'API Contact Picker è navigator.contacts.select(). Quando viene chiamato, restituisce una promessa e mostra il selettore di contatti, consentendo all'utente di selezionare i contatti che vuole condividere con il sito. Dopo aver selezionato gli elementi da condividere e aver fatto clic su Fine, la promessa viene risolta con un array di contatti selezionati dall'utente.

Quando chiami select(), devi fornire un array di proprietà che vuoi restituire come primo parametro (con i valori consentiti che sono uno qualsiasi tra 'name', 'email', 'tel', 'address' o 'icon') e, facoltativamente, se è possibile selezionare più contatti come secondo parametro.

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 può essere chiamata solo da un contesto di navigazione di primo livello sicuro e, come altre API potenti, richiede un gesto dell'utente.

Rilevamento delle proprietà disponibili

Per rilevare le proprietà disponibili, chiama navigator.contacts.getProperties(). Restituisce una promessa che viene risolta con un array di stringhe che indica quali proprietà sono disponibili. Ad esempio: ['name', 'email', 'tel', 'address']. Puoi passare questi valori a select().

Ricorda che le proprietà non sono sempre disponibili e potrebbero essere aggiunte nuove proprietà. In futuro, altre piattaforme e fonti di contatto potrebbero limitare le proprietà da condividere.

Gestione dei risultati

L'API Contact Picker restituisce un array di contatti e ogni contatto include un array delle proprietà richieste. Se un contatto non dispone di dati per la proprietà richiesta o se l'utente sceglie di disattivare la condivisione di una determinata proprietà, l'API restituisce un array vuoto. Descrivo in che modo l'utente sceglie le proprietà nella sezione Controllo utente.

Ad esempio, se un sito richiede name, email e tel e un utente seleziona un singolo contatto che ha dati nel campo del nome, fornisce due numeri di telefono, ma non ha un indirizzo email, la risposta restituita sarà:

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

Sicurezza e autorizzazioni

Il team di Chrome ha progettato e implementato l'API Contact Picker utilizzando i principi fondamentali definiti in Controlling Access to Powerful Web Platform Features, tra cui controllo utente, trasparenza ed ergonomia. Spiegherò ciascuna di queste.

Controllo utente

L'accesso ai contatti degli utenti avviene tramite il selettore e può essere chiamato solo con un gesto dell'utente, in un contesto di navigazione di primo livello sicuro. In questo modo, un sito non può mostrare il selettore al caricamento della pagina o mostrarlo in modo casuale senza alcun contesto.

Screenshot: gli utenti possono scegliere quali proprietà condividere.
Gli utenti possono scegliere di non condividere alcune proprietà. In questo screenshot, l'utente ha deselezionato il pulsante "Numeri di telefono". Anche se il sito ha richiesto i numeri di telefono, questi non verranno condivisi con il sito.

Non è disponibile un'opzione per selezionare in blocco tutti i contatti, in modo che gli utenti siano incoraggiati a selezionare solo i contatti che devono condividere per quel particolare sito web. Gli utenti possono anche controllare quali proprietà vengono condivise con il sito attivando/disattivando il pulsante della proprietà nella parte superiore del selettore.

Trasparenza

Per chiarire quali dati di contatto vengono condivisi, il selettore mostra sempre il nome e l'icona del contatto, oltre a eventuali proprietà richieste dal sito. Ad esempio, se un sito richiede name, email e tel, tutte e tre le proprietà verranno visualizzate nel selettore. In alternativa, se un sito richiede solo tel, il selettore mostrerà solo il nome e i numeri di telefono.

Screenshot del selettore per il sito che richiede tutte le proprietà.
Selettore, sito che richiede name, email e tel, un contatto selezionato.
Screenshot del selettore per il sito che richiede solo i numeri di telefono.
Selettore, sito che richiede solo tel, un contatto selezionato.
Screenshot del selettore quando viene premuto a lungo un contatto.
Il risultato di una pressione prolungata su un contatto.

Se tieni premuto a lungo un contatto, vengono visualizzate tutte le informazioni che verranno condivise se il contatto viene selezionato. (Vedi l'immagine del contatto del Gatto del Cheshire.)

Nessuna persistenza delle autorizzazioni

L'accesso ai contatti è on demand e non persistente. Ogni volta che un sito vuole accedere, deve chiamare navigator.contacts.select() con un gesto dell'utente e l'utente deve scegliere individualmente i contatti che vuole condividere con il sito.

Feedback

Il team di Chrome vuole conoscere le tue esperienze con l'API Contact Picker.

Problemi con l'implementazione?

Hai trovato un bug nell'implementazione di Chrome? O l'implementazione è diversa dalla specifica?

  • Invia una segnalazione di bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero di dettagli possibile, fornisci istruzioni semplici per riprodurre il bug e imposta Componenti su Blink>Contacts.

Hai intenzione di utilizzare l'API?

Intendi utilizzare l'API Contact Picker? Il tuo supporto pubblico aiuta il team di Chrome a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto sia fondamentale supportarle.

Link utili

Grazie

Un ringraziamento speciale a Finnur Thorarinsson e Rayan Kanso, che stanno implementando la funzionalità, e a Peter Beverloo, il cui codice ho rubato senza vergogna e sottoposto a refactoring per la demo.

P.S. I nomi nel selettore dei contatti sono personaggi di Alice nel Paese delle Meraviglie.