PWA's als URL-handlers

Laat geïnstalleerde PWA's URL's verwerken voor een meer geïntegreerde functionaliteit.

Thomas Steiner

Wat zijn PWA's als URL-handlers?

Stel je voor dat je met een vriend chat via een instant messenger-app zoals Berichten op macOS en dat jullie het over muziek hebben. Stel je ook voor dat jullie allebei de music.example.com-PWA op jullie apparaten hebben geïnstalleerd. Als je je favoriete nummer wilt delen met een vriend, kun je een deep link sturen zoals https://music.example.com/rick-astley/never-gonna-give-you-up. Omdat deze link vrij lang is, hebben de ontwikkelaars van music.example.com misschien besloten om een extra korte link aan elke track toe te voegen, zoals https://🎵.example.com/r-a/n-g-g-y-u.

Met PWA als URL-handlers kunnen apps zoals music.example.com zichzelf registreren als URL-handlers voor URL's die overeenkomen met patronen zoals https://music.example.com, https://*.music.example.com of https://🎵.example.com. Zo worden links van buiten de PWA, bijvoorbeeld vanuit een instant messenger-app of een e-mailclient, geopend in de geïnstalleerde PWA in plaats van in een browsertabblad.

PWA als URL-handlers bestaat uit 2 toevoegingen:

  1. Het lid "url_handlers" van het web-app-manifest.
  2. De bestandsindeling web-app-origin-association voor de validatie van URL-koppelingen binnen en buiten het bereik.

Voorgestelde use cases voor PWA's als URL-handlers

Voorbeelden van sites die deze API kunnen gebruiken, zijn:

  • Streamingsites voor muziek of video, zodat tracklinks of playlistlinks worden geopend in de speler van de app.
  • Nieuws- of RSS-lezers, zodat gevolgde of geabonneerde sites worden geopend in de leesmodus van de app.

PWA's gebruiken als URL-handlers

Aanzetten met about://flags

Als je lokaal wilt experimenteren met PWA's als URL-handlers, zonder een origin trial token, zet je de vlag #enable-desktop-pwas-url-handling aan in about://flags.

Het lid "url_handlers" van het web-app-manifest

Als je een geïnstalleerde PWA wilt koppelen aan URL-patronen, moet je deze patronen invoeren in het manifest van de web-app. Dit gebeurt via het "url_handlers"-lid. Het accepteert een matrix van objecten met een eigenschap origin, een vereiste string die een patroon is voor overeenkomende herkomsten. Deze patronen mogen een jokerteken (*) als voorvoegsel hebben om meerdere subdomeinen op te nemen (zoals https://*.example.com). URL's die overeenkomen met deze oorsprongen, kunnen worden verwerkt door deze web-app. Het schema wordt altijd verondersteld https:// te zijn, maar moet expliciet worden vermeld.

In het volgende fragment van een web-app-manifest zie je hoe het voorbeeld van de muziek-PWA uit de inleidende alinea dit kan instellen. De 2e vermelding met het jokerteken ("https://*.music.example.com") zorgt dat de app ook wordt geactiveerd voor https://www.music.example.com of mogelijke andere voorbeelden zoals https://marketing-activity.music.example.com.

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

Het web-app-origin-association-bestand

Omdat de PWA een andere oorsprong (music.example.com) heeft dan sommige URL's die de app moet verwerken (bijvoorbeeld https://🎵.example.com), moet de app het eigendom van deze andere oorsprongen verifiëren. Dit gebeurt in een web-app-origin-association-bestand dat wordt gehost op de andere oorsprongen.

Dit bestand moet geldige JSON bevatten. De structuur op het hoogste niveau is een object met een lid met de naam "web_apps". Dit lid is een matrix van objecten en elk object vertegenwoordigt een vermelding voor een unieke web-app. Elk object bevat:

Veld Beschrijving Type Standaard
"manifest" (Vereist) URL-tekenreeks van het web-app-manifest van de bijbehorende PWA string N.v.t.
"details" (Optioneel) Een object dat arrays van opgenomen en uitgesloten URL-patronen bevat object N.v.t.

Elk "details"-object bevat:

Veld Beschrijving Type Standaard
"paths" (Optioneel) Matrix van toegestane padtekenreeksen string[] []
"exclude_paths" (Optioneel) Matrix van niet-toegestane padtekenreeksen string[] []

Hieronder vind je een voorbeeld van een web-app-origin-association-bestand voor het voorbeeld van de muziek-PWA hierboven. Het wordt gehost op de oorsprong 🎵.example.com en brengt de koppeling tot stand met de PWA music.example.com, geïdentificeerd door de URL van het web-app-manifest.

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

Wanneer komt een URL overeen?

Een PWA komt overeen met een URL voor verwerking als aan beide van de volgende voorwaarden wordt voldaan:

  • De URL komt overeen met een van de oorsprongstekenreeksen in "url_handlers".
  • De browser kan via het betreffende web-app-origin-association-bestand valideren dat elke oorsprong ermee akkoord gaat dat deze app een dergelijke URL verwerkt.

Over de bestandsdetectie van web-app-origin-association

Ontwikkelaars moeten het web-app-origin-association-bestand in de map /.well-known/ in de root van de app plaatsen, zodat de browser het web-app-origin-association-bestand kan vinden. De bestandsnaam moet exact web-app-origin-association zijn om dit te laten werken.

Demo

Als je PWA's wilt testen als URL-handlers, stel je de browsermarkering in zoals beschreven en installeer je de PWA op https://mandymsft.github.io/pwa/. Als je het web-app-manifest bekijkt, zie je dat de app URL's verwerkt met de volgende URL-patronen: https://mandymsft.github.io en https://luhuangmsft.github.io. Omdat de laatste een andere oorsprong (luhuangmsft.github.io) heeft dan de PWA, moet de PWA op mandymsft.github.io eigendom bewijzen. Dit gebeurt via het bestand web-app-origin-association dat wordt gehost op https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Als je wilt testen of het echt werkt, stuur je jezelf een testbericht via een berichten-app naar keuze of een e-mail die je bekijkt in een e-mailclient die niet online is, zoals Mail op macOS. De e-mail of het tekstbericht moet een van de links https://mandymsft.github.io of https://luhuangmsft.github.io bevatten. Beide moeten worden geopend in de geïnstalleerde PWA.

De Windows Skype-app voor instant messaging naast de geïnstalleerde demo-PWA, die in de zelfstandige modus wordt geopend nadat er op een link is geklikt die door de app wordt verwerkt in een Skype-chatbericht.

Beveiliging en machtigingen

Het Chromium-team heeft PWA's ontworpen en geïmplementeerd als URL-handlers volgens de kernprincipes die zijn gedefinieerd in Controlling Access to Powerful Web Platform Features, waaronder gebruikersbeheer, transparantie en ergonomie.

Controle door gebruikers

Als meer dan één PWA zich registreert als URL-handler voor een bepaald URL-patroon, wordt de gebruiker gevraagd om te kiezen met welke PWA het patroon moet worden verwerkt, als dat überhaupt moet gebeuren. Navigaties die beginnen in een browsertabblad, worden niet verwerkt door dit voorstel. Het is expliciet gericht op navigaties die buiten de browser beginnen.

Transparantie

Als de vereiste koppelingsvalidatie om welke reden dan ook niet kan worden afgerond tijdens de PWA-installatie, registreert de browser de app niet als actieve URL-handler voor de betreffende URL's. Als URL-handlers onjuist zijn geïmplementeerd, kunnen ze worden gebruikt om verkeer voor websites te kapen. Daarom is het mechanisme voor app-koppeling een belangrijk onderdeel van het schema.

Platformspecifieke apps kunnen al API's van het besturingssysteem gebruiken om geïnstalleerde apps op het systeem van de gebruiker op te sommen. Apps in Windows kunnen bijvoorbeeld de API FindAppUriHandlersAsync gebruiken om URL-handlers op te sommen. Als PWA's zich registreren als URL-handlers op OS-niveau in Windows, is hun aanwezigheid zichtbaar voor andere apps.

Behoud van rechten

Een oorsprong kan de koppelingen met PWA's op elk moment wijzigen. Browsers proberen regelmatig de koppelingen van geïnstalleerde web-apps opnieuw te valideren. Als de registratie van een URL-handler niet opnieuw kan worden gevalideerd omdat de koppelingsgegevens zijn gewijzigd of niet meer beschikbaar zijn, verwijdert de browser de registraties.

Feedback

Het Chromium-team hoort graag over je ervaringen met de PWA's als URL-handlers.

Vertel ons over het API-ontwerp

Werkt de API niet zoals je verwacht? Of ontbreken er methoden of eigenschappen die je nodig hebt om je idee te implementeren? Heeft u een vraag of opmerking over het beveiligingsmodel? Dien een specificatieprobleem in bij de bijbehorende GitHub-repo of voeg je gedachten toe aan een bestaand probleem.

Een probleem met de implementatie melden

Heb je een bug gevonden in de implementatie van Chromium? Of is de implementatie anders dan de specificatie? Meld een bug op new.crbug.com. Geef zo veel mogelijk details en instructies om het probleem te reproduceren en voer UI>Browser>WebAppInstalls in het vak Components in.

Ondersteuning voor de API tonen

Ben je van plan PWA's te gebruiken als URL-handlers? Je openbare steun helpt het Chromium-team prioriteit te geven aan functies en laat andere browserleveranciers zien hoe belangrijk het is om ze te ondersteunen.

Stuur een tweet naar @ChromiumDev met de hashtag #URLHandlers en laat ons weten waar en hoe je de tool gebruikt.

Nuttige links

Erkenning

PWA's als URL-handlers zijn gespecificeerd en geïmplementeerd door Lu Huang en Mandy Chen van het Microsoft Edge-team. Dit document is beoordeeld door Joe Medley.