PWAs als URL-Handler

Installierte PWAs können URLs verarbeiten, um eine bessere Integration zu ermöglichen.

Thomas Steiner

Was sind PWAs als URL-Handler?

Stellen Sie sich vor, Sie chatten mit einem Freund über eine Instant-Messaging-Anwendung wie Messages unter macOS und unterhalten sich über Musik. Angenommen, Sie haben beide die music.example.com-PWA auf Ihren Geräten installiert. Wenn du deinen Lieblingstitel mit einem Freund teilen möchtest, kannst du ihm einen Deeplink wie https://music.example.com/rick-astley/never-gonna-give-you-up senden. Da dieser Link ziemlich lang ist, haben die Entwickler von music.example.com möglicherweise beschlossen, jedem Titel einen zusätzlichen Kurzlink hinzuzufügen, z. B. https://🎵.example.com/r-a/n-g-g-y-u.

Mit „PWA als URL-Handler“ können sich Apps wie music.example.com als URL-Handler für URLs registrieren, die Mustern wie https://music.example.com, https://*.music.example.com oder https://🎵.example.com entsprechen. So werden Links von außerhalb der PWA, z. B. von einer Instant-Messenger-Anwendung oder einem E-Mail-Client, in der installierten PWA und nicht in einem Browsertab geöffnet.

PWAs als URL-Handler bestehen aus zwei Ergänzungen:

  1. Das Web-App-Manifest-Element "url_handlers".
  2. Das web-app-origin-association-Dateiformat zum Validieren von URL-Verknüpfungen, die im und außerhalb des Bereichs liegen.

Empfohlene Anwendungsfälle für PWAs als URL-Handler

Beispiele für Websites, die diese API verwenden können:

  • Musik- oder Videostreaming-Websites, damit Links zu Titeln oder Playlists im Player der App geöffnet werden.
  • Nachrichten- oder RSS-Reader, damit gefolgte oder abonnierte Websites im Lesemodus der App geöffnet werden.

PWAs als URL-Handler verwenden

Über about://flags aktivieren

Wenn du PWAs als URL-Handler lokal ohne Ursprungstest-Token testen möchtest, aktiviere das Flag #enable-desktop-pwas-url-handling in about://flags.

Das Web-App-Manifest-Element "url_handlers"

Wenn Sie eine installierte PWA mit URL-Mustern verknüpfen möchten, müssen diese Muster im Web-App-Manifest angegeben werden. Dies geschieht über das Mitglied "url_handlers". Es wird ein Array von Objekten mit einem origin-Attribut akzeptiert. Dies ist ein erforderlicher string, der ein Muster für den Abgleich von Ursprüngen ist. Diese Muster dürfen ein Platzhalterpräfix (*) haben, um mehrere Subdomains (z. B. https://*.example.com) einzuschließen. URLs, die mit diesen Ursprüngen übereinstimmen, können von dieser Web-App verarbeitet werden. Das Schema wird immer als https:// angenommen, muss aber explizit erwähnt werden.

Der folgende Auszug aus einem Web-App-Manifest zeigt, wie das Beispiel für eine Musik-PWA aus dem einleitenden Absatz dies einrichten könnte. Der zweite Eintrag mit dem Platzhalter ("https://*.music.example.com") sorgt dafür, dass die App auch für https://www.music.example.com oder andere potenzielle Beispiele wie https://marketing-activity.music.example.com aktiviert wird.

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

Datei web-app-origin-association

Da die PWA auf einem anderen Ursprung (music.example.com) als einige der URLs liegt, die sie verarbeiten muss (z.B. https://🎵.example.com), muss die App die Eigentümerschaft dieser anderen Ursprünge bestätigen. Dies geschieht in einer web-app-origin-association-Datei, die auf den anderen Ursprüngen gehostet wird.

Diese Datei muss gültiges JSON enthalten. Die Struktur auf oberster Ebene ist ein Objekt mit einem Mitglied namens "web_apps". Dieses Mitglied ist ein Array von Objekten, wobei jedes Objekt einen Eintrag für eine eindeutige Web-App darstellt. Jedes Objekt enthält:

Feld Beschreibung Typ Standard
"manifest" (Erforderlich) URL-String des Web-App-Manifests der verknüpften PWA string –
"details" (Optional) Ein Objekt, das Arrays von eingeschlossenen und ausgeschlossenen URL-Mustern enthält object –

Jedes "details"-Objekt enthält:

Feld Beschreibung Typ Standard
"paths" (Optional) Array zulässiger Pfadstrings string[] []
"exclude_paths" (Optional) Array von unzulässigen Pfadstrings string[] []

Unten finden Sie eine web-app-origin-association-Beispieldatei für das obige Beispiel einer Musik-PWA. Sie wird auf dem Ursprung 🎵.example.com gehostet und stellt die Verknüpfung mit der PWA music.example.com her, die durch die URL des Web-App-Manifests identifiziert wird.

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

Wann stimmt eine URL überein?

Eine PWA stimmt mit einer URL überein, wenn beide der folgenden Bedingungen erfüllt sind:

  • Die URL stimmt mit einem der Ursprungsstrings in "url_handlers" überein.
  • Der Browser kann anhand der jeweiligen web-app-origin-association-Datei prüfen, ob jeder Ursprung damit einverstanden ist, dass diese App eine solche URL verarbeitet.

Informationen zur Erkennung von web-app-origin-association-Dateien

Damit der Browser die Datei web-app-origin-association finden kann, müssen Entwickler die Datei web-app-origin-association im Ordner /.well-known/ im Stammverzeichnis der App ablegen. Damit das funktioniert, muss der Dateiname genau web-app-origin-association lauten.

Demo

Wenn du PWAs als URL-Handler testen möchtest, musst du das Browser-Flag wie beschrieben festlegen und dann die PWA unter https://mandymsft.github.io/pwa/ installieren. Im Web-App-Manifest sehen Sie, dass URLs mit den folgenden URL-Mustern verarbeitet werden: https://mandymsft.github.io und https://luhuangmsft.github.io. Da die letztere einen anderen Ursprung (luhuangmsft.github.io) als die PWA hat, muss die PWA auf mandymsft.github.io die Inhaberschaft nachweisen. Dies geschieht über die Datei web-app-origin-association, die unter https://luhuangmsft.github.io/.well-known/web-app-origin-association gehostet wird.

Wenn Sie testen möchten, ob die Funktion tatsächlich funktioniert, senden Sie sich selbst eine Testnachricht über eine Messaging-App Ihrer Wahl oder eine E-Mail, die Sie in einem nicht webbasierten E-Mail-Client wie Mail unter macOS ansehen. Die E-Mail oder Nachricht sollte einen der Links https://mandymsft.github.io oder https://luhuangmsft.github.io enthalten. Beide sollten in der installierten PWA geöffnet werden.

Die Windows-Skype-Instant-Messenger-App neben der installierten Demo-PWA, die im eigenständigen Modus geöffnet wird, nachdem in einer Skype-Chatnachricht auf einen von ihr verarbeiteten Link geklickt wurde.

Sicherheit und Berechtigungen

Das Chromium-Team hat PWAs als URL-Handler nach den Grundprinzipien entworfen und implementiert, die in Controlling Access to Powerful Web Platform Features definiert sind, einschließlich Nutzerkontrolle, Transparenz und Ergonomie.

Kontrolle durch Nutzerinnen und Nutzer

Wenn sich mehrere PWAs als URL-Handler für ein bestimmtes URL-Muster registrieren, wird der Nutzer aufgefordert, auszuwählen, mit welcher PWA das Muster verarbeitet werden soll, falls überhaupt. Navigationsaktionen, die in einem Browsertab gestartet werden, werden in diesem Vorschlag nicht behandelt. Er richtet sich explizit an Navigationsaktionen, die außerhalb des Browsers gestartet werden.

Transparenz

Wenn die erforderliche Verknüpfungsvalidierung während der PWA-Installation aus irgendeinem Grund nicht erfolgreich abgeschlossen werden kann, registriert der Browser die App nicht als aktiven URL-Handler für die betroffenen URLs. URL-Handler können bei unsachgemäßer Implementierung verwendet werden, um Traffic für Websites abzufangen. Aus diesem Grund ist der Mechanismus zur App-Verknüpfung ein wichtiger Teil des Schemas.

Plattformspezifische Anwendungen können bereits Betriebssystem-APIs verwenden, um installierte Anwendungen auf dem System des Nutzers aufzulisten. Beispielsweise können Anwendungen unter Windows die API FindAppUriHandlersAsync verwenden, um URL-Handler aufzulisten. Wenn PWAs als URL-Handler auf Betriebssystemebene in Windows registriert werden, sind sie für andere Anwendungen sichtbar.

Dauerhafte Berechtigungen

Ein Ursprung kann seine Verknüpfungen mit PWAs jederzeit ändern. Browser versuchen regelmäßig, die Verknüpfungen installierter Web-Apps neu zu validieren. Wenn die Registrierung eines URL-Handlers nicht noch einmal validiert werden kann, weil sich die Verknüpfungsdaten geändert haben oder nicht mehr verfügbar sind, werden die Registrierungen vom Browser entfernt.

Feedback

Das Chromium-Team möchte mehr über Ihre Erfahrungen mit PWAs als URL-Handler erfahren.

Erzählen Sie uns etwas über das 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 und eine Anleitung zur Reproduktion an und trage UI>Browser>WebAppInstalls in das Feld Komponenten ein.

Unterstützung für die API zeigen

Planen Sie, PWAs als URL-Handler 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.

Sende einen Tweet an @ChromiumDev mit dem Hashtag #URLHandlers und teile uns mit, wo und wie du es verwendest.

Nützliche Links

Danksagungen

PWAs als URL-Handler wurden von Lu Huang und Mandy Chen vom Microsoft Edge-Team spezifiziert und implementiert. Dieses Dokument wurde von Joe Medley geprüft.