Bereikextensies voor web-apps

Vanaf Chrome 122 kun je je abonneren op de Origin-test voor het lid scope_extensions van het app-manifest. Hiermee kunnen sites die meerdere subdomeinen en top-level domeinen beheren, worden gepresenteerd als één web-app. In dit document wordt uitgelegd waarom het Chrome-team deze functie introduceert en wanneer je deze misschien wilt gebruiken.

Overzicht

Sommige web-apps hebben meerdere oorsprongen, bijvoorbeeld example.com als de hoofd-app en dan space_1.example.com, …, space_n.example.com, soms gecombineerd met special-example.com, als subfunctionaliteit, allemaal onder de hoofd-app. Dit type sitearchitectuur heeft gevolgen voor Progressive Web Apps. Beperkingen zijn onder andere dat je geen serviceworkers, apparaattypen, lokale opslag en rechten kunt delen tussen verschillende herkomsten. Ook toont cross-origin navigatie in een zelfstandige PWA een venster-UI (balk 'buiten bereik') die aangeeft dat de gebruiker de PWA-functionaliteit heeft verlaten. In de artikelen Progressive web-apps op sites met meerdere herkomsten en Meerdere progressive web-apps bouwen op hetzelfde domein vind je meer informatie over hoe je een aantal van deze problemen kunt omzeilen.

Met de Scope Extensions API kunnen web-apps een aantal van de uitdagingen overwinnen die het same-origin-beleid oplegt aan dit type sitearchitectuur. Hiermee kunnen web-apps hun bereik uitbreiden naar andere oorsprongen om een uniforme gebruikerservaring te bieden, mits er een overeenkomst is tussen de primaire oorsprong van de web-app en de bijbehorende oorsprongen.

Doelen

Het belangrijkste doel van de Scope Extensions API is om sites die meerdere subdomeinen en top-level domeinen beheren, zich te laten gedragen als één aaneengesloten web-app als het gaat om de UI van de web-app en het vastleggen van links. Bijvoorbeeld door de site example.com die example.com.co.uk en support.example.com omvat, zich zo veel mogelijk als één web-app te laten gedragen.

Diagram van een hoofd-PWA en bijbehorende subfunctionaliteit.

Met Scope Extensions kunnen PWA's met meerdere oorsprongen zich gedragen als een aaneengesloten web-app als het gaat om de UI van de web-app.

In de praktijk vertaalt dit zich in 2 specifiekere doelen:

  • Cross-origin navigatie: Sta gebruikers toe om tussen gekoppelde origins te navigeren zonder de gebruikerservaring te verstoren door een venster-UI aan te roepen die de gebruiker laat weten dat die de PWA verlaat.
  • Cross-origin linkvastlegging: Toestaan dat web-apps gebruikersnavigaties vastleggen naar sites waarmee ze zijn gelieerd.

Cross-origin in-scope navigatie

Als gebruikers standaard tussen oorsprongen navigeren in een zelfstandige PWA, krijgen ze een venster-UI te zien die aangeeft dat ze de PWA-functionaliteit verlaten. In Chrome bestaat deze UI uit een balk 'buiten bereik' die de URL van de nieuwe oorsprong bevat. Dit is verstorend voor de gebruikerservaring, omdat gebruikers verwachten dat ze binnen dezelfde app-context blijven navigeren, maar het gevoel kunnen hebben dat ze uit de app worden gehaald.

Balk buiten bereik bovenaan een zelfstandige PWA.

De balk 'Buiten bereik' die in Chrome wordt getoond als gebruikers tussen verschillende oorsprongen navigeren in een zelfstandige PWA.

Met bereikextensies wordt de UI van het venster niet getoond als gebruikers naar een van de bijbehorende oorsprongen gaan, zodat de PWA wordt gepresenteerd als een uniforme functionaliteit.

Linkvastlegging verwijst naar de mogelijkheid van een app om links binnen het bereik vast te leggen. De manier waarop dit wordt geïmplementeerd, verschilt per browser en besturingssysteem. In Chrome op ChromeOS openen links binnen het bereik van een geïnstalleerde PWA bijvoorbeeld standaard een browsertabblad met een indicatie in de adresbalk dat er een app is die deze links kan verwerken. De gebruiker kan zich vanaf dat moment aanmelden voor automatische linkvastlegging.

Omnibox-prompt voor een geïnstalleerde PWA.

Fragment van de Chrome-adresbalk voor een tabblad in ChromeOS met een visuele indicatie dat de link kan worden verwerkt door een PWA en de optie om die beslissing te onthouden.

Als een gebruiker op een link klikt die buiten het bereik van de PWA valt (waaronder links naar subdomeinen of top-level domeinen), wordt de gebruiker niet herkend als behorend tot de PWA. Links worden bijvoorbeeld geopend in een browsertabblad zonder dat de gebruiker een indicatie krijgt dat er een app is die de link kan verwerken. Met de Scope Extensions API kun je het bereik van de PWA uitbreiden, zodat de bijbehorende herkomsten worden behandeld als links binnen het bereik.

Implementatie

Als je bereikextensies wilt implementeren, moet je de relatie tussen de hoofdoorsprong en de bijbehorende oorsprongen vaststellen.

De lijst met bijbehorende oorsprongen declareren

Voeg een scope_extensions-web-app-manifestlid toe aan de hoofd-PWA-oorsprong om de web-app in staat te stellen het bereik uit te breiden naar andere oorsprongen.

Web-app-manifest (https://example.com)

{
  "id": "/",
  "name": "Example",
  "display": "standalone",
  "start_url": "/index.html",
  "scope_extensions": [
    { "type": "origin", "origin": "https://help.example.com" },
    { "type": "origin", "origin": "https://example.co.uk" },
    { "type": "origin", "origin": "https://help.example.co.uk" }
  ]
}

Koppelingen bevestigen

Elk van de vermelde oorsprongen bevestigt de koppeling met de web-app via een /.well-known/web-app-origin-association-configuratiebestand. Dit bestand moet de naam web-app-origin-association hebben en op deze exacte locatie worden aangeboden, omdat het een bekende URI is.

/.well-known/web-app-origin-association (gekoppelde oorsprong)

{
  "https://example.com/": {
    "scope": "/"
  }
}

In het bestand staan de web-apps waarmee de oorsprong is gekoppeld. Elke sleutel is de manifest-ID van de web-app en elke waarde kan een optioneel bereik instellen dat relatief is aan de bijbehorende oorsprong. Als je het bereik weglaat, wordt standaard '/' gebruikt.

Demo

De demo bestaat uit 2 sites:

Als je de volgende tests wilt uitvoeren, moet je de vlag about://flags/#enable-desktop-pwas-scope-extensions aanzetten (beschikbaar vanaf Chrome v115).

Cross-origin-navigatie testen

Open als voorwaarde voor deze tests de hoofd-PWA in een browser, installeer deze als PWA en open deze om de PWA in de zelfstandige modus uit te voeren. De PWA bevat links naar een oorsprong in het uitgebreide bereik en naar een oorsprong die niet in het uitgebreide bereik valt.

Het hoofdvenster van de PWA met links binnen het bereik en links met een uitgebreid bereik.

Demo-PWA met links naar oorsprong in uitgebreid bereik en oorsprong niet in uitgebreid bereik.

Standaard cross-origin navigatie (niet in uitgebreid bereik)

  1. Klik op de link naar de oorsprong die niet binnen het uitgebreide bereik valt in de PWA op volledig scherm.
  2. De navigatie wordt uitgevoerd en de balk 'Buiten bereik' wordt getoond.

Het hoofdvenster van de PWA met de balk Buiten bereik nadat u op de link Buiten bereik heeft geklikt.

De balk 'Buiten bereik' wordt standaard getoond voor een cross-origin navigatie voor een PWA in de zelfstandige modus.

Cross-origin navigatie met bereikextensies (in uitgebreid bereik)

  1. Ga terug naar de homepage van de PWA.
  2. Klik op de link naar de oorsprong die niet binnen het uitgebreide bereik valt.
  3. Standaard wordt er een balk 'buiten bereik' getoond, maar vanwege de koppeling met bereikextensies is dat niet het geval.

Het hoofdvenster van de PWA zonder de balk Buiten bereik nadat u op de link Uitgebreid bereik heeft geklikt.

De balk 'Buiten bereik' wordt niet getoond in cross-origin navigatie nadat de oorsprongskoppeling is gemaakt met bereikextensies.

  1. Open en installeer de hoofd-PWA op een ChromeOS-apparaat.
  2. Klik op de volgende link: bijbehorende oorsprong.
  3. De link wordt geopend in een nieuw browsertabblad en er wordt een prompt getoond om de link te openen in de geïnstalleerde PWA.

Omnibox-prompt voor een geïnstalleerde PWA met uitgebreid bereik.

Als je op een link naar de bijbehorende oorsprong van een PWA klikt, wordt de link geopend in een nieuw tabblad en wordt het icoon Openen in app getoond, zodat de gebruiker zich kan aanmelden voor automatische linkvastlegging.

Origin-proefperiode

Als je deze API in je app wilt testen met echte gebruikers, kun je dit doen met een origin trial. Met Origin trials kun je experimentele functies uitproberen met je gebruikers door een testtoken te verkrijgen dat aan je domein is gekoppeld. Daarna kun je je app implementeren en verwachten dat deze werkt in een browser die de functie ondersteunt die je test (in dit geval is deze beschikbaar in Chrome 121 tot en met 126). Vul het aanvraagformulier in om je eigen token te krijgen om een origin trial uit te voeren.

Feedback

Het Chrome-team is op zoek naar feedback over het nut van deze API. Als je het team wilt helpen deze API te verbeteren met feedback over het nut ervan en nieuwe use cases die niet in de huidige versie zijn opgenomen, open je een probleem op GitHub.

Aanvullende bronnen

Erkenning

Met speciale dank aan het team dat deze API heeft ontwikkeld. Scope-extensies zijn gespecificeerd door Alan Cutter en Lu Huang, met input van Matt Giuca. De API is geïmplementeerd door Alan Cutter van Google Chrome en Hassan Talat, Kristin Lee en Lu Huang van Microsoft Edge.