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. Es ist einer der häufigsten Feature-Wünsche von Webentwicklern und oft der Hauptgrund, warum sie eine iOS-/Android-App entwickeln.

Die Contact Picker API-Spezifikation ist ab Chrome 80 unter Android M oder höher verfügbar. Sie ist eine On-Demand-API, mit der Nutzer Einträge aus ihrer Kontaktliste auswählen und eingeschränkte Details der ausgewählten Einträge mit einer Website teilen können. Nutzer können nur das teilen, was sie möchten, und es ist einfacher, mit Freunden und Familie in Kontakt zu 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 nachsehen, welche Telefonnummer angerufen werden soll. Oder ein soziales Netzwerk könnte einem Nutzer helfen, herauszufinden, welche Freunde bereits beigetreten sind.

Contact Picker API verwenden

Für die Contact Picker API ist ein Methodenaufruf mit einem Optionsparameter erforderlich, 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);

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

Kontakte auswählen

Der Einstiegspunkt für die Contact Picker API ist navigator.contacts.select(). Wenn die Funktion aufgerufen wird, wird ein Promise zurückgegeben und die Kontaktauswahl wird angezeigt, sodass der Nutzer die Kontakte auswählen kann, die er für die Website freigeben möchte. Nachdem der Nutzer ausgewählt hat, was freigegeben werden soll, und auf Fertig geklickt hat, wird das Promise mit einem Array der vom Nutzer ausgewählten Kontakte aufgelöst.

Wenn Sie select() aufrufen, müssen Sie als ersten Parameter ein Array von Eigenschaften angeben, die zurückgegeben werden sollen. Die zulässigen Werte sind 'name', 'email', 'tel', 'address' oder 'icon'. 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 über einen sicheren Browsing-Kontext der obersten Ebene aufgerufen werden und erfordert wie andere leistungsstarke APIs eine Nutzeraktion.

Verfügbare Attribute erkennen

Rufen Sie navigator.contacts.getProperties() auf, um zu ermitteln, welche Attribute verfügbar sind. Es wird ein Promise zurückgegeben, das mit einem Array von Strings aufgelöst wird, die angeben, welche Eigenschaften verfügbar sind. Beispiel: ['name', 'email', 'tel', 'address'] Sie können diese Werte an select() übergeben.

Beachten Sie, dass Eigenschaften nicht immer verfügbar sind und neue Eigenschaften hinzugefügt werden können. In Zukunft kann es sein, dass andere Plattformen und Kontaktquellen einschränken, welche Eigenschaften geteilt werden.

Umgang mit den Ergebnissen

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

Wenn eine Website beispielsweise name, email und tel anfordert und ein Nutzer einen einzelnen Kontakt auswählt, der Daten im Namensfeld hat, zwei Telefonnummern angibt, aber keine E-Mail-Adresse, 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 unter Berücksichtigung der in Controlling Access to Powerful Web Platform Features definierten Grundsätze entwickelt und implementiert, darunter Nutzerkontrolle, Transparenz und Ergonomie. Ich erkläre sie alle.

Kontrolle durch Nutzer

Der Zugriff auf die Kontakte der Nutzer erfolgt über die Auswahl und kann nur mit einer Nutzeraktion in einem sicheren Browsing-Kontext der obersten Ebene aufgerufen werden. So wird verhindert, dass der Picker beim Laden einer Seite oder ohne Kontext angezeigt wird.

Screenshot: Nutzer können auswählen, welche Properties sie freigeben möchten.
Nutzer können auswählen, dass bestimmte Properties nicht freigegeben werden. Auf diesem Screenshot hat der Nutzer die Schaltfläche „Telefonnummern“ deaktiviert. Auch wenn die Website nach Telefonnummern gefragt hat, werden diese nicht an die Website weitergegeben.

Es gibt keine Option, alle Kontakte gleichzeitig auszuwählen. Nutzer sollen nur die Kontakte auswählen, die sie für die jeweilige Website freigeben möchten. Nutzer können auch festlegen, welche Properties für die Website freigegeben werden, indem sie oben in der Auswahl auf die Property-Schaltfläche klicken.

Transparenz

Damit klar ist, welche Kontaktdaten freigegeben werden, werden in der Auswahl immer der Name und das Symbol des Kontakts sowie alle Eigenschaften angezeigt, die von der Website angefordert wurden. Wenn für eine Website beispielsweise name, email und tel angefordert werden, werden alle drei Eigenschaften in der Auswahl angezeigt. Wenn auf einer Website nur tel angefordert wird, werden in der Auswahl nur der Name und die Telefonnummern angezeigt.

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

Wenn Sie lange auf einen Kontakt tippen, werden alle Informationen angezeigt, die freigegeben werden, wenn der Kontakt ausgewählt wird. (Siehe das Kontaktbild „Cheshire Cat“.)

Keine Berechtigungspersistenz

Der Zugriff auf Kontakte erfolgt bei Bedarf und die Daten werden nicht gespeichert. Jedes Mal, wenn eine Website auf Kontakte zugreifen möchte, muss sie navigator.contacts.select() mit einer Nutzeraktion aufrufen. Der Nutzer muss dann einzeln auswählen, welche Kontakte er mit der Website teilen möchte.

Feedback

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

Probleme bei der Implementierung?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden? Oder weicht die Implementierung von der Spezifikation ab?

  • Melden Sie einen Fehler unter https://new.crbug.com. Geben Sie so viele Details wie möglich an, stellen Sie eine einfache Anleitung zum Reproduzieren des Fehlers bereit und legen Sie Components auf Blink>Contacts fest.

Sie planen, die API zu verwenden?

Planen 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 an Finnur Thorarinsson und Rayan Kanso, die die Funktion implementieren, und an Peter Beverloo, dessen Code ich für die Demo schamlos kopiert und refaktoriert habe.

PS: Die Namen in meiner Kontaktauswahl sind Figuren aus „Alice im Wunderland“.