PWA come gestori URL

Consenti alle PWA installate di gestire gli URL per un'esperienza più integrata.

Thomas Steiner

Che cosa sono le PWA come gestori di URL?

Immagina di chattare con un amico utilizzando un'applicazione di messaggistica istantanea come Messaggi su macOS e di parlare di musica. Immagina inoltre che entrambi abbiate installato la PWA di music.example.com sui vostri dispositivi. Se vuoi condividere la tua traccia preferita con un amico, puoi inviargli un deep link come https://music.example.com/rick-astley/never-gonna-give-you-up. Poiché questo link è piuttosto lungo, gli sviluppatori di music.example.com potrebbero aver deciso di aggiungere un link breve aggiuntivo a ogni traccia, ad esempio https://🎵.example.com/r-a/n-g-g-y-u.

La funzionalità PWA come gestori di URL consente ad app come music.example.com di registrarsi come gestori di URL per URL che corrispondono a pattern come https://music.example.com, https://*.music.example.com o https://🎵.example.com, in modo che i link esterni alla PWA, ad esempio da un'applicazione di messaggistica istantanea o da un client di posta, si aprano nella PWA installata anziché in una scheda del browser.

La funzionalità PWA come gestori di URL è composta da due aggiunte:

  1. Il membro del manifest dell'app web "url_handlers".
  2. Il formato file web-app-origin-association per la convalida delle associazioni di URL inclusi ed esclusi dall'ambito.

Casi d'uso suggeriti per le PWA come gestori di URL

Ecco alcuni esempi di siti che potrebbero utilizzare questa API:

  • Siti di streaming di musica o video, in modo che i link alle tracce o alle playlist si aprano nell'esperienza del player dell'app.
  • Lettori di notizie o RSS, in modo che i siti seguiti o a cui hai effettuato l'iscrizione si aprano nella modalità Lettura dell'app.

Come utilizzare le PWA come gestori di URL

Attivazione con about://flags

Per sperimentare con le PWA come gestori di URL localmente, senza un token di origin trial, attiva il flag #enable-desktop-pwas-url-handling in about://flags.

Il membro del manifest dell'app web "url_handlers"

Per associare una PWA installata a pattern URL, questi pattern devono essere specificati nel manifest dell'app web. Questo avviene tramite il membro "url_handlers". Accetta un array di oggetti con una proprietà origin, che è un string obbligatorio che funge da pattern per la corrispondenza delle origini. Questi pattern possono avere un prefisso con carattere jolly (*) per includere più sottodomini (come https://*.example.com). Gli URL che corrispondono a queste origini potrebbero essere gestiti da questa app web. Lo schema è sempre considerato https://, ma deve essere menzionato esplicitamente.

Il seguente estratto di un manifest dell'app web mostra come l'esempio di PWA musicale del paragrafo introduttivo potrebbe configurare questa impostazione. La seconda voce con il carattere jolly ("https://*.music.example.com") garantisce che l'app venga attivata anche per https://www.music.example.com o altri potenziali esempi come https://marketing-activity.music.example.com.

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

Il file web-app-origin-association

Poiché la PWA si trova su un'origine (music.example.com) diversa rispetto ad alcuni degli URL che deve gestire (ad es. https://🎵.example.com), l'app deve verificare la proprietà di queste altre origini. Questo avviene in un file web-app-origin-association ospitato sulle altre origini.

Questo file deve contenere un JSON valido. La struttura di primo livello è un oggetto con un membro denominato "web_apps". Questo membro è un array di oggetti e ogni oggetto rappresenta una voce per un'app web univoca. Ogni oggetto contiene:

Campo Descrizione Tipo Predefinito
"manifest" (Obbligatorio) Stringa URL del manifest dell'app web della PWA associata string N/D
"details" (Facoltativo) Un oggetto che contiene array di pattern URL inclusi ed esclusi object N/D

Ogni oggetto "details" contiene:

Campo Descrizione Tipo Predefinito
"paths" (Facoltativo) Array di stringhe di percorsi consentiti string[] []
"exclude_paths" (Facoltativo) Array di stringhe di percorsi non consentiti string[] []

Di seguito è riportato un esempio di file web-app-origin-association per l'esempio di PWA musicale riportato sopra. Viene ospitato nell'origine 🎵.example.com e stabilisce l'associazione con la PWA music.example.com, identificata dall'URL del manifest dell'app web.

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

Quando un URL corrisponde?

Una PWA corrisponde a un URL per la gestione se vengono soddisfatte entrambe le seguenti condizioni:

  • L'URL corrisponde a una delle stringhe di origine in "url_handlers".
  • Il browser è in grado di convalidare, utilizzando il rispettivo file web-app-origin-association, che ogni origine accetta di consentire a questa app di gestire un URL di questo tipo.

Informazioni sul rilevamento dei file web-app-origin-association

Affinché il browser possa rilevare il file web-app-origin-association, gli sviluppatori devono inserire il file web-app-origin-association nella cartella /.well-known/ nella directory root dell'app. Affinché funzioni, il nome del file deve essere esattamente web-app-origin-association.

Demo

Per testare le PWA come gestori di URL, assicurati di impostare il flag del browser come descritto e poi installa la PWA all'indirizzo https://mandymsft.github.io/pwa/. Se esamini il suo manifesto dell'app web, puoi vedere che gestisce gli URL con i seguenti pattern URL: https://mandymsft.github.io e https://luhuangmsft.github.io. Poiché quest'ultima si trova su un'origine diversa (luhuangmsft.github.io) rispetto alla PWA, la PWA su mandymsft.github.io deve dimostrare la proprietà, il che avviene utilizzando il file web-app-origin-association ospitato all'indirizzo https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Per verificare che funzioni, inviati un messaggio di prova utilizzando un'app di messaggistica immediata di tua scelta o un'email visualizzata in un client di posta non basato sul web, come Mail su macOS. L'email o il messaggio deve contenere uno dei link https://mandymsft.github.io o https://luhuangmsft.github.io. Entrambi dovrebbero aprirsi nella PWA installata.

L'app di messaggistica istantanea Skype per Windows accanto alla PWA demo installata, che viene aperta in modalità autonoma dopo aver fatto clic su un link gestito dalla PWA in un messaggio chat di Skype.

Sicurezza e autorizzazioni

Il team di Chromium ha progettato e implementato le PWA come gestori di URL utilizzando i principi fondamentali definiti in Controlling Access to Powerful Web Platform Features, tra cui il controllo utente, la trasparenza e l'ergonomia.

Controllo utenti

Se più PWA si registrano come gestori di URL per un determinato pattern URL, all'utente verrà chiesto di scegliere con quale PWA vuole gestire il pattern, se vuole farlo. Le navigazioni che iniziano in una scheda del browser non sono gestite da questa proposta, che è esplicitamente rivolta alle navigazioni che iniziano al di fuori del browser.

Trasparenza

Se, per qualsiasi motivo, non è possibile completare correttamente la convalida dell'associazione necessaria durante l'installazione della PWA, il browser non registrerà l'app come gestore di URL attivo per gli URL interessati. Se implementati in modo errato, i gestori di URL possono essere utilizzati per intercettare il traffico dei siti web. Per questo motivo, il meccanismo di associazione delle app è una parte importante dello schema.

Le applicazioni specifiche per la piattaforma possono già utilizzare le API del sistema operativo per enumerare le applicazioni installate sul sistema dell'utente. Ad esempio, le applicazioni su Windows possono utilizzare l'API FindAppUriHandlersAsync per enumerare i gestori di URL. Se le PWA si registrano come gestori di URL a livello di sistema operativo in Windows, la loro presenza sarà visibile ad altre applicazioni.

Persistenza delle autorizzazioni

Un'origine può modificare le sue associazioni con le PWA in qualsiasi momento. I browser tenteranno regolarmente di riconvalidare le associazioni delle app web installate. Se la convalida di una registrazione del gestore di URL non va a buon fine perché i dati dell'associazione sono stati modificati o non sono più disponibili, il browser rimuoverà le registrazioni.

Feedback

Il team di Chromium vuole conoscere le tue esperienze con le PWA come gestori di URL.

Parlaci della progettazione dell'API

C'è qualcosa nell'API che non funziona come previsto? Oppure mancano metodi o proprietà di cui hai bisogno per implementare la tua idea? Hai una domanda o un commento sul modello di sicurezza? Invia una segnalazione relativa alle specifiche nel repository GitHub corrispondente o aggiungi le tue considerazioni a un problema esistente.

Segnala un problema relativo all'implementazione

Hai trovato un bug nell'implementazione di Chromium? Oppure l'implementazione è diversa dalla specifica? Segnala un bug all'indirizzo new.crbug.com. Assicurati di includere il maggior numero di dettagli possibile, le istruzioni per la riproduzione e inserisci UI>Browser>WebAppInstalls nella casella Componenti.

Mostra il supporto per l'API

Hai intenzione di utilizzare le PWA come gestori di URL? Il tuo supporto pubblico aiuta il team di Chromium a dare la priorità alle funzionalità e mostra agli altri fornitori di browser quanto sia fondamentale supportarle.

Invia un tweet a @ChromiumDev utilizzando l'hashtag #URLHandlers e facci sapere dove e come lo utilizzi.

Link utili

Ringraziamenti

Le PWA come gestori di URL sono state specificate e implementate da Lu Huang e Mandy Chen del team di Microsoft Edge. Questo documento è stato rivisto da Joe Medley.