Kontaktauswahl für das Web

Die Contact Picker API bietet Nutzern eine einfache Möglichkeit, Kontakte aus ihrer Kontaktliste freizugeben.

Was ist die Contact Picker API?

Der Zugriff auf die Kontakte des Nutzers über ein Mobilgerät war seit fast frühen Tagen eine Funktion von iOS-/Android-Apps. Das ist eine der häufigsten Funktionsanfragen von Webentwicklern und oft der Hauptgrund dafür, dass sie eine iOS-/Android-App entwickeln.

Die ab Chrome 80 unter Android M oder höher verfügbare Contact Picker API-Spezifikation ist eine On-Demand-API, mit der Nutzer Einträge aus ihrer Kontaktliste auswählen und bestimmte Details der ausgewählten Einträge mit einer Website teilen können. Nutzer können so jederzeit nur Inhalte teilen, die sie möchten. Außerdem können sie so einfacher mit Freunden und Familienmitgliedern in Kontakt treten.

Ein webbasierter E-Mail-Client könnte beispielsweise die Contact Picker API verwenden, um die Empfänger einer E-Mail auszuwählen. Eine Voice-over-IP-App könnte nach einer Telefonnummer suchen, die angerufen werden soll. Oder ein soziales Netzwerk könnte Nutzern helfen, herauszufinden, welche Freunde bereits beigetreten sind.

Contact Picker API verwenden

Die Contact Picker API erfordert einen Methodenaufruf mit einem Optionsparameter, der die gewünschten Arten von Kontaktdaten angibt. Eine zweite Methode gibt an, welche Informationen das zugrunde liegende System bereitstellt.

Funktionserkennung

So prüfen Sie, ob die Contact Picker API unterstützt wird:

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

Darüber hinaus ist unter Android Android M oder höher für die Kontaktauswahl erforderlich.

Öffnen der Kontaktauswahl

Der Einstiegspunkt für die Contact Picker API ist navigator.contacts.select(). Beim Aufruf wird ein Promise zurückgegeben und die Kontaktauswahl angezeigt, mit der der Nutzer die Kontakte auswählen kann, die er für die Website freigeben möchte. Nachdem du ausgewählt hast, was du teilen möchtest, und auf Done (Fertig) klickst, wird das Promise mit einem Array von Kontakten aufgelöst, die der Nutzer ausgewählt hat.

Beim Aufrufen von select() müssen Sie ein Array mit Attributen angeben, die als erster Parameter zurückgegeben werden sollen. Zulässige Werte sind 'name', 'email', 'tel', 'address' oder 'icon'. Optional können Sie auch festlegen, ob mehrere Kontakte als zweiter Parameter ausgewählt werden können.

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

Die Contacts Picker API kann nur aus einem sicheren Browserkontext auf oberster Ebene aufgerufen werden. Wie andere leistungsstarke APIs ist auch eine Nutzergeste erforderlich.

Verfügbare Attribute erkennen

Rufen Sie navigator.contacts.getProperties() auf, um zu ermitteln, welche Unterkünfte verfügbar sind. Sie gibt ein Versprechen zurück, das mit einem Array von Strings aufgelöst wird, das angibt, welche Eigenschaften verfügbar sind. Beispiel: ['name', 'email', 'tel', 'address'] Sie können diese Werte an select() übergeben.

Beachten Sie, dass Attribute nicht immer verfügbar sind und unter Umständen neue Attribute hinzugefügt werden. In Zukunft wird die Freigabe von Properties durch andere Plattformen und Kontaktquellen eingeschränkt.

Umgang mit den Ergebnissen

Die Contact Picker API gibt ein Array von Kontakten zurück und jeder Kontakt enthält ein Array der angeforderten Eigenschaften. Wenn ein Kontakt für die angeforderte Property keine Daten hat oder der Nutzer die Freigabe einer bestimmten Property deaktiviert, gibt die API ein leeres Array zurück. Ich erkläre im Abschnitt Nutzersteuerung, wie der Nutzer die Eigenschaften auswählt.

Wenn eine Website beispielsweise name, email und tel anfordert und ein Nutzer einen einzelnen Kontakt mit Daten im Namensfeld auswählt und zwei Telefonnummern, aber keine E-Mail-Adresse angibt, wird folgende Antwort zurückgegeben:

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

Sicherheit und Berechtigungen

Das Chrome-Team hat die Contact Picker API nach den unter Zugriff auf leistungsstarke Webplattform-Funktionen steuern definierten Kernprinzipien wie Nutzersteuerung, Transparenz und Ergonomie entwickelt und implementiert. Ich erkläre ihnen das im Detail.

Nutzersteuerung

Der Zugriff auf die Kontakte des Nutzers erfolgt über die Auswahl und kann nur mit einer Nutzergeste in einem sicheren Browserkontext auf oberster Ebene aufgerufen werden. Dadurch wird sichergestellt, dass die Auswahl beim Seitenaufbau nicht auf einer Website oder nach dem Zufallsprinzip ohne Kontext eingeblendet wird.

Screenshot: Nutzer können auswählen, welche Properties geteilt werden sollen.
Nutzer können einige Properties nicht gemeinsam nutzen. In diesem Screenshot hat der Nutzer die Schaltfläche „Telefonnummern“ deaktiviert. Auch wenn von der Website nach Telefonnummern gefragt wurde, werden diese nicht an die Website weitergegeben.

Es gibt keine Möglichkeit, alle Kontakte auf einmal auszuwählen, damit Nutzer nur die Kontakte auswählen können, die sie für eine bestimmte Website freigeben müssen. Nutzer können auch steuern, welche Properties für die Website freigegeben werden, indem sie oben in der Auswahl auf die Schaltfläche für die Property umschalten.

Transparenz

Zur Klarstellung, welche Kontaktdetails freigegeben werden, zeigt die Auswahl immer den Namen und das Symbol des Kontakts sowie alle Eigenschaften an, die die Website angefordert hat. Wenn eine Website beispielsweise name, email und tel anfordert, werden alle drei Unterkünfte in der Auswahl angezeigt. Wenn eine Website nur tel anfordert, werden in der Auswahl nur der Name und die Telefonnummern angezeigt.

Screenshot der Auswahl für die Website, die alle Properties anfordert.
Auswahl, Website anfordern name, email und tel, ein Kontakt ausgewählt.
Screenshot der Auswahl für eine Website, die nur Telefonnummern anfordert
Auswahl, Website nur tel, ein Kontakt ausgewählt.
Screenshot der Auswahl, wenn ein Kontakt lange gedrückt wird.
Ergebnis des langen Drückens auf einen Kontakt.

Durch langes Drücken auf einen Kontakt werden alle Informationen angezeigt, die bei ausgewähltem Kontakt freigegeben werden. (Siehe Kontaktbild von Cheshire Cat.)

Keine Berechtigungspersistenz

Der Zugriff auf Kontakte ist bei Bedarf und nicht dauerhaft. Jedes Mal, wenn eine Website auf sie zugreifen möchte, muss sie mit einer Nutzergeste navigator.contacts.select() aufrufen und der Nutzer muss die Kontakte, die er für die Website freigeben möchte, einzeln auswählen.

Feedback

Das Chrome-Team möchte mehr über Ihre Erfahrungen mit der Contact Picker API hören.

Probleme bei der Implementierung?

Haben Sie einen Fehler bei der Implementierung in Chrome gefunden? Oder unterscheidet sich die Implementierung von der Spezifikation?

  • Melde einen Fehler unter https://new.crbug.com. Gib so viele Details wie möglich an, stelle eine einfache Anleitung zum Reproduzieren des Fehlers bereit und setze Components auf Blink>Contacts. Glitch eignet sich hervorragend zur schnellen und einfachen Reproduktion von Problemen.

Möchten Sie die API verwenden?

Möchten Sie die Contact Picker API verwenden? Ihre öffentliche Unterstützung hilft dem Chrome-Team, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

Nützliche Links

Viele Grüße

Ein großes Dankeschön an Finnur Thorarinsson und Rayan Kanso, die die Funktion implementieren, sowie Peter Beverloo, dessen Code ich schamlos geklaut und für die Demo refaktoriert habe.

PS: Die Namen in meiner Kontaktauswahl sind Zeichen aus Alice im Wunderland.