Kontaktauswahl für das Web

Mit der Contact Picker API können Nutzer ganz einfach Kontakte aus ihrer Kontaktliste teilen.

Pete LePage

Was ist die Contact Picker API?

Der Zugriff auf die Kontakte des Nutzers auf einem Mobilgerät ist seit (fast) Anbeginn der Zeit eine Funktion von iOS-/Android-Apps. Das ist eine der häufigsten Funktionsanfragen, die ich von Webentwicklern höre, und oft der Hauptgrund, warum sie eine iOS-/Android-App entwickeln.

Die Contact Picker API-Spezifikation ist ab Chrome 80 unter Android M und höher verfügbar. Sie ist eine On-Demand-API, mit der Nutzer Einträge aus ihrer Kontaktliste auswählen und bestimmte Details zu den ausgewählten Einträgen mit einer Website teilen können. Nutzer können so selbst entscheiden, was sie wann teilen möchten, und es ist einfacher, mit Freunden und Familie in Kontakt zu bleiben.

Ein webbasierter E-Mail-Client kann beispielsweise die Contact Picker API verwenden, um die Empfänger einer E-Mail auszuwählen. Eine Voice-over-IP-App könnte nachsehen, welche Telefonnummer angerufen werden soll. Oder ein soziales Netzwerk könnte Nutzern zeigen, 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 Aufschluss darüber, 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);

Außerdem ist für die Kontaktauswahl unter Android Android M oder höher erforderlich.

Kontaktauswahl öffnen

Der Einstiegspunkt für die Contact Picker API ist navigator.contacts.select(). Wenn die Funktion aufgerufen wird, gibt sie ein Versprechen zurück und zeigt die Kontaktauswahl an, über die der Nutzer die Kontakte auswählen kann, die er für die Website freigeben möchte. Nachdem der Nutzer ausgewählt hat, was er freigeben möchte, und auf Fertig geklickt hat, wird das Versprechen mit einer Reihe von vom Nutzer ausgewählten Kontakten aufgelöst.

Wenn Sie select() aufrufen, müssen Sie als ersten Parameter ein Array mit den Eigenschaften angeben, die zurückgegeben werden sollen. Als zulässige Werte sind 'name', 'email', 'tel', 'address' oder 'icon' zulässig. Optional können Sie als zweiten Parameter angeben, ob mehrere Kontakte 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 von einem sicheren Browserkontext auf oberster Ebene aufgerufen werden. Wie bei anderen leistungsstarken APIs ist auch hier eine Nutzergeste erforderlich.

Verfügbare Unterkünfte erkennen

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

Denken Sie daran, dass Eigenschaften nicht immer verfügbar sind und neue hinzugefügt werden können. In Zukunft können andere Plattformen und Kontaktquellen einschränken, welche Properties weitergegeben werden.

Umgang mit den Ergebnissen

Die Contact Picker API gibt ein Array von Kontakten zurück. Jeder Kontakt enthält ein Array der angeforderten Properties. Wenn ein Kontakt keine Daten für die angeforderte Property hat oder der Nutzer die Freigabe einer bestimmten Property deaktiviert, gibt die API ein leeres Array zurück. Wie der Nutzer Eigenschaften auswählt, wird im Abschnitt Nutzersteuerung beschrieben.

Wenn eine Website beispielsweise name, email und tel anfordert und ein Nutzer einen einzelnen Kontakt auswählt, der Daten im Feld „Name“ enthält, zwei Telefonnummern angibt, aber keine E-Mail-Adresse hat, wird die 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 anhand der in Controlling Access to Powerful Web Platform Features (Zugriff auf leistungsstarke Funktionen der Webplattform steuern) definierten Grundprinzipien entwickelt und implementiert, einschließlich Nutzersteuerung, Transparenz und Ergonomie. Ich erkläre Ihnen die einzelnen Optionen.

Nutzersteuerung

Der Zugriff auf die Kontakte der Nutzer erfolgt über die Auswahl. Sie kann nur mit einer Nutzergeste in einem sicheren Browserkontext der obersten Ebene aufgerufen werden. So wird verhindert, dass eine Website die Auswahl beim Laden der Seite anzeigt oder sie zufällig ohne Kontext anzeigt.

Screenshot: Nutzer können auswählen, welche Eigenschaften sie teilen möchten.
Nutzer können festlegen, dass bestimmte Properties nicht freigegeben werden. In diesem Screenshot hat der Nutzer das Häkchen bei „Telefonnummern“ entfernt. Auch wenn von der Website die Eingabe von Telefonnummern angefordert wurde, werden diese nicht an die Website weitergegeben.

Es gibt keine Option zum Bulk-Auswählen aller Kontakte. Nutzer sollten daher nur die Kontakte auswählen, die sie für diese Website freigeben möchten. Nutzer können auch festlegen, welche Properties mit der Website geteilt werden. Dazu müssen sie oben in der Auswahl die Property-Schaltfläche aktivieren oder deaktivieren.

Transparenz

Damit klar ist, welche Kontaktdaten weitergegeben werden, werden in der Auswahl immer der Name und das Symbol des Kontakts sowie alle Eigenschaften angezeigt, die die Website angefordert hat. Wenn eine Website beispielsweise name, email und tel anfordert, werden alle drei Properties 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 eine Website, in der alle Unterkünfte angefordert werden.
Auswahl, Website fordert name, email und tel an, ein Kontakt ausgewählt.
Screenshot der Auswahl für eine Website, auf der nur Telefonnummern abgefragt werden
Auswahl, Website fordert nur tel an, ein Kontakt ausgewählt.
Screenshot der Auswahl, wenn ein Kontakt lange gedrückt wird
Das Ergebnis des langen Drückens auf einen Kontakt.

Wenn Sie einen Kontakt lange gedrückt halten, werden alle Informationen angezeigt, die weitergegeben werden, wenn der Kontakt ausgewählt wird. (Siehe Kontaktbild „Die Grinsekatze“.)

Keine Berechtigungspersistenz

Der Zugriff auf Kontakte erfolgt auf Abruf und wird nicht gespeichert. Jedes Mal, wenn eine Website Zugriff benötigt, muss sie navigator.contacts.select() mit einer Nutzergeste aufrufen. Der Nutzer muss dann die Kontakte einzeln auswählen, die er für die Website freigeben möchte.

Feedback

Das Chrome-Team möchte von Ihnen wissen, wie Sie die Contact Picker API bisher erlebt haben.

Probleme bei der Implementierung?

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

  • Melden Sie den Fehler unter https://new.crbug.com. Geben Sie dabei so viele Details wie möglich an, machen Sie eine einfache Anleitung zum Nachstellen des Fehlers und setzen Sie Components auf Blink>Contacts. Glitch eignet sich hervorragend, um Probleme schnell und einfach reproduzieren zu können.

Möchten Sie die API verwenden?

Beabsichtigen Sie, die Contact Picker API zu 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

Vielen Dank

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

PS: Die Namen in meinem Kontakt-Picker sind Figuren aus Alice im Wunderland.