Registratie van URL-protocolhandler voor PWA's

Laat geïnstalleerde PWA's links verwerken die een specifiek protocol gebruiken voor een meer geïntegreerde functionaliteit.

Thomas Steiner

Achtergrond van schema's (ook wel protocollen genoemd)

Een Uniform Resource Identifier (URI) is een compacte reeks tekens die een abstracte of fysieke bron identificeert. Elke URI begint met een schemanaam die verwijst naar een specificatie voor de toewijzing van ID's binnen dat schema. De URI-syntaxis is dus een gefedereerd en uitbreidbaar naamgevingssysteem waarin de specificatie van elk schema de syntaxis en semantiek van ID's die dat schema gebruiken, verder kan beperken. Schema's worden ook wel protocollen genoemd. Hieronder staan enkele voorbeelden van schema's.

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

De term Uniform Resource Locator (URL) verwijst naar de subset van URI's die, naast het identificeren van een bron, een manier bieden om de bron te vinden door het primaire toegangsmechanisme te beschrijven (bijvoorbeeld de netwerklocatie).

Achtergrondinformatie over de registerProtocolHandler()-methode

De methode Navigator (alleen beveiligde content) registerProtocolHandler() laat sites registreren dat ze bepaalde URL-schema's kunnen openen of verwerken. Sites moeten de methode daarom zo aanroepen: navigator.registerProtocolHandler(scheme, url). De 2 parameters worden als volgt gedefinieerd:

  • scheme: Een tekenreeks met het protocol dat de site wil verwerken.
  • url: Een tekenreeks met de URL van de handler. Deze URL moet %s bevatten als tijdelijke aanduiding die wordt vervangen door de URL met escape-tekens die moet worden verwerkt.

Het schema moet een van de schema's op de toelatingslijst zijn (bijvoorbeeld mailto, bitcoin of magnet) of beginnen met web+, gevolgd door minstens één of meer ASCII-letters in kleine letters na het voorvoegsel web+, zoals web+coffee.

Hier is een concreet voorbeeld van het proces om dit duidelijker te maken:

  1. De gebruiker bezoekt een site op https://coffeeshop.example.com/ die de volgende aanroep doet: navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s').
  2. Op een later moment, tijdens een bezoek aan https://randomsite.example.com/, klikt de gebruiker op een link zoals <a href="web+coffee:latte-macchiato">All about latte macchiato</a>.
  3. Hierdoor gaat de browser naar de volgende URL: https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato. De URL-gedecodeerde zoekreeks is dan ?type=web+coffee://latte-macchiato.

Wat protocolverwerking is

Het huidige mechanisme voor registratie van URL-protocolhandlers voor PWA's is bedoeld om registratie van protocolhandlers aan te bieden als onderdeel van een PWA-installatie via het manifest. Nadat een PWA is geregistreerd als protocolhandler, wordt de geregistreerde PWA geopend en krijgt deze de URL als een gebruiker op een hyperlink met een specifiek schema klikt, zoals mailto, bitcoin of web+music, vanuit een browser of een platformspecifieke app. Het is belangrijk om te weten dat zowel de voorgestelde op manifest gebaseerde registratie als de traditionele registerProtocolHandler() in de praktijk vergelijkbare rollen spelen, terwijl ze nog steeds de mogelijkheid bieden voor aanvullende gebruikerservaringen:

  • Overeenkomsten zijn onder andere vereisten voor de lijst met schema's die mogen worden geregistreerd en de naam en indeling van parameters.
  • De verschillen in de op manifest gebaseerde registratie zijn subtiel, maar kunnen nuttig zijn om de gebruikerservaring voor PWA-gebruikers te verbeteren. Voor op manifest gebaseerde PWA-registratie is bijvoorbeeld geen aanvullende gebruikersactie vereist, afgezien van de door de gebruiker gestarte installatie van de PWA.

Toepassingen

  • In een PWA voor tekstverwerking komt de gebruiker in een document een link naar een presentatie tegen, zoals web+presentations://deck2378465. Als de gebruiker op de link klikt, wordt de presentatie-PWA automatisch geopend in het juiste bereik en wordt de diapresentatie getoond.
  • In een platformspecifieke chat-app krijgt de gebruiker in een chatbericht een link naar een magnet-URL. Als de gebruiker op de link klikt, wordt een geïnstalleerde torrent-PWA gestart en begint de download.
  • De gebruiker heeft een PWA voor muziekstreaming geïnstalleerd. Als een vriend een link naar een nummer zoals web+music://songid=1234&time=0:13 deelt en de gebruiker erop klikt, wordt de PWA voor muziekstreaming automatisch gestart in een zelfstandig venster.

Registratie van URL-protocolhandler voor PWA's gebruiken

De API voor de registratie van de URL-protocolhandler is grotendeels gebaseerd op navigator.registerProtocolHandler(). Alleen wordt de informatie deze keer declaratief doorgegeven via het web-app-manifest in een nieuwe property met de naam "protocol_handlers" die een array van objecten met de 2 vereiste sleutels "protocol" en "url" gebruikt. Het volgende codefragment toont hoe je web+tea en web+coffee registreert. De waarden zijn tekenreeksen die de URL van de handler bevatten met de vereiste %s-tijdelijke aanduiding voor de URL met escape-teken.

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

Meerdere apps die zich registreren voor hetzelfde protocol

Als meerdere apps zich registreren als handlers voor hetzelfde schema, bijvoorbeeld het protocol mailto, toont het besturingssysteem de gebruiker een kiezer en kan die beslissen welke van de geregistreerde handlers moet worden gebruikt.

Dezelfde app die zich registreert voor meerdere protocollen

Dezelfde app kan zichzelf registreren voor meerdere protocollen, zoals je kunt zien in het codevoorbeeld.

App-updates en handlerregistratie

Handlerregistraties worden gesynchroniseerd met de nieuwste manifestversie die door de app wordt geleverd. Er zijn 2 gevallen:

  • Een update die nieuwe handlers toevoegt, activeert de registratie van handlers (los van de app-installatie).
  • Een update die handlers verwijdert, activeert de registratie van de handler (los van de verwijdering van de app).

Foutopsporing voor protocolhandlers in DevTools

Ga naar het gedeelte Protocol Handlers (Protocolhandlers) via het deelvenster Application (App) > Manifest. Je kunt hier alle beschikbare protocollen bekijken en testen.

Protocolhandlers in het deelvenster Manifest

Beveiligingsoverwegingen

Omdat voor de installatie van een PWA de context beveiligd moet zijn, neemt protocolverwerking deze beperking over. De lijst met geregistreerde protocolhandlers wordt op geen enkele manier aan het web blootgesteld, dus kan niet worden gebruikt als vector voor vingerafdrukken.

Navigatiepogingen die niet door de gebruiker zijn gestart

Navigatiepogingen die niet door de gebruiker worden gestart, maar die programmatisch zijn, mogen geen apps openen. De URL van het aangepaste protocol mag alleen worden gebruikt in browsecontexten op het hoogste niveau, maar niet bijvoorbeeld als de URL van een iframe.

Toelatingslijst van protocollen

Net als bij registerProtocolHandler() is er een toelatingslijst met protocollen die apps kunnen registreren om te verwerken.

Als de PWA voor het eerst wordt gestart vanwege een aangeroepen protocol, krijgt de gebruiker een dialoogvenster voor rechten. In dit dialoogvenster staan de app-naam en de herkomst van de app. De gebruiker wordt gevraagd of de app links van het protocol mag verwerken. Als een gebruiker het dialoogvenster voor rechten weigert, wordt de geregistreerde protocolhandler genegeerd door het besturingssysteem. Als de gebruiker de registratie van de protocolhandler ongedaan wil maken, moet die de PWA verwijderen die de handler heeft geregistreerd. De browser maakt de registratie van de protocolhandler ook ongedaan als de gebruiker Mijn keuze onthouden selecteert en daarna Niet toestaan selecteert.

Feedback

Het Chromium-team wil graag weten wat je ervaringen zijn met de registratie van URL-protocolhandlers voor PWA's.

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? Dien een bug in 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 registratie van URL-protocolhandler voor PWA's te gebruiken? Met je openbare steun help je het Chromium-team om prioriteit te geven aan functies en laat je andere browserleveranciers zien hoe belangrijk het is om deze te ondersteunen.

Deel hoe je de API wilt gebruiken in het WICG Discourse-gesprek. Stuur een tweet naar @ChromiumDev met de hashtag #ProtocolHandler en laat ons weten waar en hoe je de tool gebruikt.

Erkenning

Registratie van URL-protocolhandler voor PWA's is geïmplementeerd en gespecificeerd door Fabio Rocha, Diego González, Connor Moody en Samuel Tang van het Microsoft Edge-team. Dit document is beoordeeld door Joe Medley en Fabio Rocha.