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.

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.

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.
Cross-origin links vastleggen
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.

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:
- Hoofd-PWA: De daadwerkelijke PWA die de lijst met bijbehorende oorsprongen aangeeft via het lid
scope_extensionsin het web-app-manifest. - Oorsprong in uitgebreid bereik: Een oorsprong buiten het bereik van de hoofd-PWA, maar die eraan is gekoppeld nadat deze door de hoofd-PWA is vermeld als een gekoppelde oorsprong en de relatie is bevestigd via het
web-app-origin-association-bestand.
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.

Demo-PWA met links naar oorsprong in uitgebreid bereik en oorsprong niet in uitgebreid bereik.
Standaard cross-origin navigatie (niet in uitgebreid bereik)
- Klik op de link naar de oorsprong die niet binnen het uitgebreide bereik valt in de PWA op volledig scherm.
- De navigatie wordt uitgevoerd en de balk 'Buiten bereik' wordt getoond.

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)
- Ga terug naar de homepage van de PWA.
- Klik op de link naar de oorsprong die niet binnen het uitgebreide bereik valt.
- Standaard wordt er een balk 'buiten bereik' getoond, maar vanwege de koppeling met bereikextensies is dat niet het geval.

De balk 'Buiten bereik' wordt niet getoond in cross-origin navigatie nadat de oorsprongskoppeling is gemaakt met bereikextensies.
Cross-origin linkvastlegging testen
- Open en installeer de hoofd-PWA op een ChromeOS-apparaat.
- Klik op de volgende link: bijbehorende oorsprong.
- De link wordt geopend in een nieuw browsertabblad en er wordt een prompt getoond om de link te openen in de geïnstalleerde PWA.

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
- Scope Extensions API - Origin Trial
- Chrome-status: Web App Scope Extensions
- Uitleg over bereikextensies voor web-apps
- Intent to Experiment
- Mozilla Standards Position
- Apple Standards Position
- Chromium-bug
- Progressive web-apps op sites met meerdere oorsprongen
- Meerdere progressive web-apps maken in hetzelfde domein
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.