PWA en tant que gestionnaires d'URL

Laissez les PWA installées gérer les URL pour une expérience plus intégrée.

Thomas Steiner

Qu'est-ce que les PWA en tant que gestionnaires d'URL ?

Imaginez que vous discutez de musique avec un ami à l'aide d'une application de messagerie instantanée comme Messages sur macOS. Imaginons également que vous ayez tous les deux installé la PWA music.example.com sur vos appareils. Si vous souhaitez partager votre titre préféré avec un ami, vous pouvez lui envoyer un lien profond tel que https://music.example.com/rick-astley/never-gonna-give-you-up. Comme ce lien est assez long, les développeurs de music.example.com ont peut-être décidé d'ajouter un lien court supplémentaire à chaque titre, par exemple https://🎵.example.com/r-a/n-g-g-y-u.

La fonctionnalité "PWA en tant que gestionnaires d'URL" permet aux applications telles que music.example.com de s'enregistrer en tant que gestionnaires d'URL pour les URL correspondant à des modèles tels que https://music.example.com, https://*.music.example.com ou https://🎵.example.com. Ainsi, les liens provenant de l'extérieur de la PWA (par exemple, d'une application de messagerie instantanée ou d'un client de messagerie) s'ouvrent dans la PWA installée plutôt que dans un onglet du navigateur.

La fonctionnalité "PWA as URL Handlers" (PWA en tant que gestionnaires d'URL) se compose de deux ajouts :

  1. Membre du fichier manifeste de l'application Web "url_handlers".
  2. Format de fichier web-app-origin-association permettant de valider les associations d'URL incluses et exclues.

Cas d'utilisation suggérés pour les PWA en tant que gestionnaires d'URL

Voici quelques exemples de sites pouvant utiliser cette API :

  • Sites de streaming de musique ou de vidéo, afin que les liens vers des titres ou des playlists s'ouvrent dans le lecteur de l'application.
  • Lecteurs d'actualités ou RSS, de sorte que les sites suivis ou auxquels l'utilisateur est abonné s'ouvrent dans le mode lecteur de l'application.

Utiliser des PWA comme gestionnaires d'URL

Activer avec about://flags

Pour tester les PWA en tant que gestionnaires d'URL localement, sans jeton d'essai Origin Trial, activez l'option #enable-desktop-pwas-url-handling dans about://flags.

Le membre du fichier manifeste d'application Web "url_handlers"

Pour associer une PWA installée à des formats d'URL, ces formats doivent être spécifiés dans le fichier manifeste de l'application Web. Cela se produit via le membre "url_handlers". Elle accepte un tableau d'objets avec une propriété origin, qui est une string obligatoire correspondant à un modèle de mise en correspondance des origines. Ces formats peuvent avoir un préfixe générique (*) afin d'inclure plusieurs sous-domaines (comme https://*.example.com). Les URL correspondant à ces origines peuvent être gérées par cette application Web. Le schéma est toujours supposé être https://, mais il doit être explicitement mentionné.

L'extrait de fichier manifeste d'application Web suivant montre comment l'exemple de PWA musicale du paragraphe d'introduction peut configurer cela. La deuxième entrée avec le caractère générique ("https://*.music.example.com") garantit que l'application est également activée pour https://www.music.example.com ou d'autres exemples potentiels tels que https://marketing-activity.music.example.com.

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

Le fichier web-app-origin-association

Étant donné que la PWA se trouve sur une origine différente (music.example.com) de certaines des URL qu'elle doit gérer (par exemple, https://🎵.example.com), l'application doit vérifier la propriété de ces autres origines. Cela se produit dans un fichier web-app-origin-association hébergé sur les autres origines.

Ce fichier doit contenir du code JSON valide. La structure de premier niveau est un objet, avec un membre nommé "web_apps". Ce membre est un tableau d'objets, et chaque objet représente une entrée pour une application Web unique. Chaque objet contient :

Champ Description Type Par défaut
"manifest" (Obligatoire) Chaîne d'URL du fichier manifeste de l'application Web de la PWA associée string N/A
"details" (Facultatif) Objet contenant des tableaux de formats d'URL inclus et exclus object N/A

Chaque objet "details" contient les éléments suivants :

Champ Description Type Par défaut
"paths" (Facultatif) Tableau de chaînes de chemin d'accès autorisées string[] []
"exclude_paths" (Facultatif) Tableau de chaînes de chemins d'accès non autorisés string[] []

Voici un exemple de fichier web-app-origin-association pour l'exemple de PWA de musique ci-dessus. Il serait hébergé sur l'origine 🎵.example.com et établirait l'association avec la PWA music.example.com, identifiée par l'URL de son fichier manifeste d'application Web.

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

Quand une URL correspond-elle ?

Une PWA correspond à une URL à gérer si les deux conditions suivantes sont remplies :

  • L'URL correspond à l'une des chaînes d'origine dans "url_handlers".
  • Le navigateur peut valider, à l'aide du fichier web-app-origin-association respectif, que chaque origine accepte que cette application gère une telle URL.

À propos de la découverte de fichiers web-app-origin-association

Pour que le navigateur découvre le fichier web-app-origin-association, les développeurs doivent placer le fichier web-app-origin-association dans le dossier /.well-known/ à la racine de l'application. Pour que cela fonctionne, le nom du fichier doit être exactement web-app-origin-association.

Démo

Pour tester les PWA en tant que gestionnaires d'URL, veillez à définir l'indicateur du navigateur comme indiqué, puis installez la PWA sur https://mandymsft.github.io/pwa/. En consultant son fichier manifeste d'application Web, vous pouvez voir qu'elle gère les URL avec les formats d'URL suivants : https://mandymsft.github.io et https://luhuangmsft.github.io. Comme ce dernier se trouve sur une origine différente (luhuangmsft.github.io) de la PWA, la PWA sur mandymsft.github.io doit prouver qu'elle en est propriétaire, ce qui se fait à l'aide du fichier web-app-origin-association hébergé à l'adresse https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Pour vérifier que cela fonctionne, envoyez-vous un message de test à l'aide de l'application de chat de votre choix ou un e-mail consulté dans un client de messagerie non Web, comme Mail sur macOS. L'e-mail ou le message doit contenir l'un des liens https://mandymsft.github.io ou https://luhuangmsft.github.io. Les deux doivent s'ouvrir dans la PWA installée.

L'application de messagerie instantanée Skype pour Windows à côté de la PWA de démonstration installée, qui s'ouvre en mode autonome après avoir cliqué sur un lien géré par celle-ci dans un message de chat Skype.

Sécurité et autorisations

L'équipe Chromium a conçu et implémenté les PWA en tant que gestionnaires d'URL en utilisant les principes fondamentaux définis dans Contrôler l'accès aux fonctionnalités puissantes de la plate-forme Web, y compris le contrôle utilisateur, la transparence et l'ergonomie.

Contrôle des utilisateurs

Si plusieurs PWA s'enregistrent en tant que gestionnaires d'URL pour un format d'URL donné, l'utilisateur sera invité à choisir la PWA avec laquelle il souhaite gérer le format, le cas échéant. Les navigations qui commencent dans un onglet de navigateur ne sont pas gérées par cette proposition, qui vise explicitement les navigations qui commencent en dehors du navigateur.

Transparence

Si, pour une raison quelconque, la validation de l'association nécessaire ne peut pas être effectuée lors de l'installation de la PWA, le navigateur n'enregistrera pas l'application en tant que gestionnaire d'URL actif pour les URL concernées. S'ils ne sont pas correctement implémentés, les gestionnaires d'URL peuvent être utilisés pour détourner le trafic des sites Web. C'est pourquoi le mécanisme d'association d'applications est un élément important du schéma.

Les applications spécifiques à une plate-forme peuvent déjà utiliser les API du système d'exploitation pour énumérer les applications installées sur le système de l'utilisateur. Par exemple, les applications sous Windows peuvent utiliser l'API FindAppUriHandlersAsync pour énumérer les gestionnaires d'URL. Si les PWA s'enregistrent en tant que gestionnaires d'URL au niveau de l'OS dans Windows, leur présence est visible par les autres applications.

Persistance des autorisations

Une origine peut modifier ses associations avec des PWA à tout moment. Les navigateurs tenteront régulièrement de revalider les associations des applications Web installées. Si la revalidation de l'enregistrement d'un gestionnaire d'URL échoue parce que les données d'association ont changé ou ne sont plus disponibles, le navigateur supprime les enregistrements.

Commentaires

L'équipe Chromium souhaite connaître votre expérience avec les PWA en tant que gestionnaires d'URL.

Parlez-nous de la conception de l'API

L'API ne fonctionne pas comme vous l'attendiez ? Ou manque-t-il des méthodes ou des propriétés dont vous avez besoin pour implémenter votre idée ? Vous avez une question ou un commentaire sur le modèle de sécurité ? Signalez un problème de spécification dans le dépôt GitHub correspondant ou ajoutez vos commentaires à un problème existant.

Signaler un problème d'implémentation

Avez-vous trouvé un bug dans l'implémentation de Chromium ? Ou l'implémentation est-elle différente de la spécification ? Signalez un bug sur new.crbug.com. Veillez à inclure autant de détails que possible, ainsi que des instructions pour reproduire le problème, et saisissez UI>Browser>WebAppInstalls dans le champ Components (Composants).

Afficher la compatibilité avec l'API

Prévoyez-vous d'utiliser des PWA comme gestionnaires d'URL ? Votre soutien public aide l'équipe Chromium à prioriser les fonctionnalités et montre aux autres fournisseurs de navigateurs l'importance de les prendre en charge.

Envoyez un tweet à @ChromiumDev en utilisant le hashtag #URLHandlers et indiquez-nous où et comment vous l'utilisez.

Liens utiles

Remerciements

Les PWA en tant que gestionnaires d'URL ont été spécifiées et implémentées par Lu Huang et Mandy Chen de l'équipe Microsoft Edge. Ce document a été examiné par Joe Medley.