Registrierung des URL-Protokoll-Handlers für PWAs

Installierte PWAs können Links verarbeiten, die ein bestimmtes Protokoll verwenden, um eine bessere Integration zu ermöglichen.

Thomas Steiner

Hintergrundinformationen zu Schemas (auch Protokolle genannt)

Ein Uniform Resource Identifier (URI) ist eine kompakte Zeichenfolge, die eine abstrakte oder physische Ressource identifiziert. Jeder URI beginnt mit einem Schemanamen, der sich auf eine Spezifikation zum Zuweisen von Kennungen innerhalb dieses Schemas bezieht. Die URI-Syntax ist also ein föderiertes und erweiterbares Benennungssystem, bei dem die Spezifikation jedes Schemas die Syntax und Semantik von Kennungen, die dieses Schema verwenden, weiter einschränken kann. Schemas werden auch als Protokolle bezeichnet. Hier sehen Sie einige Beispiele für Schemas.

tel:+1-816-555-1212
mailto:Jane.Doe@example.com
news:comp.infosystems.www.servers.unix
https://web.dev/

Der Begriff Uniform Resource Locator (URL) bezieht sich auf die Teilmenge der URIs, die neben der Identifizierung einer Ressource auch eine Möglichkeit bieten, die Ressource zu finden, indem sie ihren primären Zugriffsmechanismus (z.B. ihren Netzwerkstandort) beschreiben.

Hintergrund zur registerProtocolHandler()-Methode

Mit der Methode Navigator registerProtocolHandler(), die nur für sichere Inhalte gilt, können Websites ihre Fähigkeit registrieren, bestimmte URL-Schemas zu öffnen oder zu verarbeiten. Daher müssen Websites die Methode so aufrufen: navigator.registerProtocolHandler(scheme, url). Die beiden Parameter sind so definiert:

  • scheme: Ein String, der das Protokoll enthält, das die Website verarbeiten möchte.
  • url: Ein String, der die URL des Handlers enthält. Diese URL muss %s als Platzhalter enthalten, der durch die zu verarbeitende maskierte URL ersetzt wird.

Das Schema muss entweder eines der auf der Zulassungsliste stehenden Schemas sein (z. B. mailto, bitcoin oder magnet) oder mit web+ beginnen, gefolgt von mindestens einem oder mehreren ASCII-Kleinbuchstaben nach dem Präfix web+, z. B. web+coffee.

Hier ist ein konkretes Beispiel für den Ablauf:

  1. Der Nutzer besucht eine Website unter https://coffeeshop.example.com/, die den folgenden Aufruf ausführt: navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s').
  2. Später klickt der Nutzer beim Besuch von https://randomsite.example.com/ auf einen Link wie <a href="web+coffee:latte-macchiato">All about latte macchiato</a>.
  3. Dadurch wird der Browser zur folgenden URL weitergeleitet: https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato. Der URL-decodierte Suchstring lautet dann ?type=web+coffee://latte-macchiato.

Worum es bei der Protokollverarbeitung geht

Der aktuelle Mechanismus zur Registrierung von URL-Protokoll-Handlern für PWAs bietet die Registrierung von Protokoll-Handlern als Teil einer PWA-Installation über das Manifest. Wenn ein Nutzer nach der Registrierung einer PWA als Protokoll-Handler in einem Browser oder einer plattformspezifischen App auf einen Hyperlink mit einem bestimmten Schema wie mailto, bitcoin oder web+music klickt, wird die registrierte PWA geöffnet und die URL empfangen. Sowohl die vorgeschlagene manifestbasierte Registrierung als auch die herkömmliche registerProtocolHandler() spielen in der Praxis eine sehr ähnliche Rolle, ermöglichen aber dennoch komplementäre Nutzererfahrungen:

  • Zu den Ähnlichkeiten gehören Anforderungen an die Liste der zulässigen Schemas, den Namen und das Format von Parametern usw.
  • Die Unterschiede bei der manifestbasierten Registrierung sind gering, können aber nützlich sein, um die Nutzerfreundlichkeit für PWA-Nutzer zu verbessern. Für die manifestbasierte PWA-Registrierung ist beispielsweise möglicherweise keine zusätzliche Nutzeraktion erforderlich, abgesehen von der vom Nutzer initiierten Installation der PWA.

Anwendungsfälle

  • In einer Textverarbeitungs-PWA stößt der Nutzer in einem Dokument auf einen Link zu einer Präsentation wie web+presentations://deck2378465. Wenn der Nutzer auf den Link klickt, wird die Präsentations-PWA automatisch im richtigen Bereich geöffnet und die Präsentation angezeigt.
  • In einer plattformspezifischen Chat-App erhält der Nutzer in einer Chatnachricht einen Link zu einer magnet-URL. Wenn der Nutzer auf den Link klickt, wird eine installierte Torrent-PWA gestartet und der Download beginnt.
  • Der Nutzer hat eine PWA für Musikstreaming installiert. Wenn ein Freund einen Link zu einem Song wie web+music://songid=1234&time=0:13 teilt und der Nutzer darauf klickt, wird die Musikstreaming-PWA automatisch in einem eigenständigen Fenster gestartet.

URL-Protokoll-Handler-Registrierung für PWAs verwenden

Die API für die Registrierung von URL-Protokoll-Handlern ist eng an navigator.registerProtocolHandler() angelehnt. Diesmal werden die Informationen jedoch deklarativ über das Web-App-Manifest in einem neuen Attribut namens "protocol_handlers" übergeben, das ein Array von Objekten mit den beiden erforderlichen Schlüsseln "protocol" und "url" enthält. Das folgende Code-Snippet zeigt, wie web+tea und web+coffee registriert werden. Die Werte sind Strings, die die URL des Handlers mit dem erforderlichen Platzhalter %s für die maskierte URL enthalten.

{
  "protocol_handlers": [
    {
      "protocol": "web+tea",
      "url": "/tea?type=%s"
    },
    {
      "protocol": "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}

Mehrere Apps, die sich für dasselbe Protokoll registrieren

Wenn sich mehrere Anwendungen als Handler für dasselbe Schema registrieren, z. B. für das Protokoll mailto, zeigt das Betriebssystem dem Nutzer eine Auswahl an, damit er entscheiden kann, welcher der registrierten Handler verwendet werden soll.

Dieselbe App registriert sich für mehrere Protokolle.

Dieselbe App kann sich für mehrere Protokolle registrieren, wie im Codebeispiel zu sehen ist.

App-Updates und Handler-Registrierung

Handler-Registrierungen werden mit der neuesten Manifestversion synchronisiert, die von der App bereitgestellt wird. Es gibt zwei Fälle:

  • Ein Update, das neue Handler hinzufügt, löst die Handler-Registrierung aus (getrennt von der App-Installation).
  • Ein Update, bei dem Handler entfernt werden, löst die Abmeldung des Handlers aus (unabhängig von der Deinstallation der App).

Debugging von Protokoll-Handlern in den Entwicklertools

Rufen Sie den Bereich Anwendung > Manifest auf und gehen Sie zum Abschnitt Protokoll-Handler. Hier können Sie alle verfügbaren Protokolle ansehen und testen.

Protokoll-Handler im Bereich „Manifest“

Sicherheitsaspekte

Da für die Installation von PWAs ein sicherer Kontext erforderlich ist, gilt diese Einschränkung auch für die Protokollverarbeitung. Die Liste der registrierten Protokoll-Handler wird in keiner Weise im Web offengelegt und kann daher nicht als Fingerprinting-Vektor verwendet werden.

Nicht vom Nutzer initiierte Navigationsversuche

Navigationsversuche, die nicht vom Nutzer initiiert, sondern programmatisch sind, dürfen keine Apps öffnen. Die URL des benutzerdefinierten Protokolls darf nur in Browserkontexten der obersten Ebene verwendet werden, aber nicht beispielsweise als URL eines iFrames.

Zulassungsliste der Protokolle

Wie bei registerProtocolHandler() gibt es eine Zulassungsliste mit Protokollen, die Apps zur Verarbeitung registrieren können.

Beim ersten Start der PWA aufgrund eines aufgerufenen Protokolls wird dem Nutzer ein Dialogfeld zur Berechtigung angezeigt. In diesem Dialogfeld werden der Name und die Herkunft der App angezeigt und der Nutzer wird gefragt, ob die App Links aus dem Protokoll verarbeiten darf. Wenn ein Nutzer das Dialogfeld für die Berechtigung ablehnt, wird der registrierte Protokoll-Handler vom Betriebssystem ignoriert. Wenn der Nutzer die Registrierung des Protokoll-Handlers aufheben möchte, muss er die PWA deinstallieren, die ihn registriert hat. Der Browser hebt die Registrierung des Protokoll-Handlers auch auf, wenn der Nutzer „Auswahl merken“ und „Nicht zulassen“ auswählt.

Feedback

Das Chromium-Team möchte von Ihren Erfahrungen mit der Registrierung von URL-Protokoll-Handlern für PWAs hören.

Informationen zum API-Design

Gibt es etwas an der API, das nicht wie erwartet funktioniert? Oder fehlen Methoden oder Properties, die Sie für die Umsetzung Ihrer Idee benötigen? Haben Sie eine Frage oder einen Kommentar zum Sicherheitsmodell? Melde ein Problem mit der Spezifikation im entsprechenden GitHub-Repository oder füge deine Gedanken zu einem bestehenden Problem hinzu.

Problem mit der Implementierung melden

Haben Sie einen Fehler in der Chromium-Implementierung gefunden? Oder unterscheidet sich die Implementierung von der Spezifikation? Melde den Fehler unter new.crbug.com. Gib so viele Details wie möglich an, füge eine Anleitung zur Reproduktion hinzu und gib UI>Browser>WebAppInstalls in das Feld Components ein.

Unterstützung für die API zeigen

Planen Sie, die Registrierung der URL-Protokoll-Handler für PWAs zu verwenden? Ihre öffentliche Unterstützung hilft dem Chromium-Team, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

Teilen Sie im WICG-Discourse-Thread mit, wie Sie die Funktion verwenden möchten. Senden Sie einen Tweet an @ChromiumDev mit dem Hashtag #ProtocolHandler und teilen Sie uns mit, wo und wie Sie die Funktion verwenden.

Danksagungen

Die Registrierung der URL-Protokoll-Handler für PWAs wurde von Fabio Rocha, Diego González, Connor Moody und Samuel Tang vom Microsoft Edge-Team implementiert und spezifiziert. Dieses Dokument wurde von Joe Medley und Fabio Rocha geprüft.