Votre application est-elle installée ? L'API Get Installed Related Apps vous le dira !

Pete LePage

Alexey Rodionov

L'API Get Installed Related Apps permet d'obtenir la liste des applications associées installées, ainsi que des informations les concernant.

Il vous permet de vérifier si votre progressive web app (PWA), votre application Android ou votre application Universal Windows Platform (UWP) est installée sur l'appareil actuel, à la fois à partir de la PWA elle-même et à partir d'une page Web associée (par exemple, un site Web de marketing produit).

Bubblewrap est un ensemble de bibliothèques Open Source et un outil de ligne de commande (CLI) pour Node.js. Bubblewrap est développé par l'équipe Google Chrome pour aider les développeurs à générer, compiler et signer un projet Android qui lance votre PWA en tant qu'activité Web fiable (TWA).

PWABuilder est un projet Open Source développé par Microsoft. Il permet aux développeurs d'empaqueter et de signer leurs PWA pour les publier sur différentes plates-formes, y compris le Microsoft Store, le Google Play Store, l'App Store et le Meta Quest Store. Pour ce faire, ils doivent saisir l'URL d'une PWA, saisir/modifier les métadonnées de l'application, puis cliquer sur le bouton "Générer".

PWABuilder utilise Bubblewrap en arrière-plan pour empaqueter les PWA pour Android et ChromeOS.

Si l'application est déjà installée, vous pouvez personnaliser l'expérience utilisateur.

Exemple :

• Ne faites pas la promotion de l'installation de votre PWA si votre autre application est déjà installée.
• Rediriger l'utilisateur depuis un site Web de marketing produit directement vers votre application.
• Nous centralisons certaines fonctionnalités, comme les notifications, dans l'autre application pour éviter les notifications en double.

Pour utiliser l'API Get Installed Related Apps, vous devez indiquer à votre application l'existence de votre page, puis indiquer à votre page l'existence de votre application. Une fois que vous avez défini la relation entre les deux, vous pouvez vérifier si l'application associée est installée.

Pour éviter que les sites testent un ensemble trop large de leurs propres applications, seules les trois premières applications déclarées dans le fichier manifeste de l'application Web seront prises en compte.

Comme la plupart des autres API Web puissantes, l'API Get Installed Related Apps n'est disponible que lorsqu'elle est diffusée via HTTPS.

Qu'est-ce que l'API Get Installed Related Apps ?

L'appel de la méthode asynchrone navigator.getInstalledRelatedApps() renvoie une promesse qui se résout avec un tableau d'objets contenant des informations sur les applications qui :

• installée sur l'appareil actuel ;
• défini dans le champ related_applications du fichier manifeste de l'application Web ;
• avoir une relation validée avec une page sur laquelle la méthode navigator.getInstalledRelatedApps() est appelée (consultez les sections suivantes pour en savoir plus).

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

L'appel console.log(installedRelatedApps) renvoie un résultat semblable au suivant :

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

Par exemple, pour vérifier si des applications associées sont installées sur l'appareil de l'utilisateur, vous pouvez utiliser la ligne de code suivante :

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

Si vous connaissez l'ID du package, vous pouvez utiliser la commande suivante pour obtenir le numéro de version de l'application Android associée installée :

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

Cela signifie que la méthode navigator.getInstalledRelatedApps() renverra toujours les applications associées installées, même si leur version est inférieure à min_version ou si leur certificat de signature ne correspond à aucun fingerprints déclaré dans le champ related_applications du fichier manifeste de l'application Web.

Types d'applications compatibles que vous pouvez vérifier

Vérifier si votre application Android est installée

Votre site Web peut vérifier si votre application Android est installée.

Android uniquement : Chrome 80 ou version ultérieure

Indiquer à votre application Android l'existence de votre site Web

Vous devez d'abord mettre à jour votre application Android pour définir la relation entre votre site Web et votre application Android à l'aide du système Digital Asset Links. Cela permet de vérifier que seul votre site Web peut vérifier si votre application Android est installée.

Dans le AndroidManifest.xml de votre application Android, ajoutez une entrée asset_statements :

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

Ensuite, dans strings.xml, ajoutez la déclaration d'assets suivante, en remplaçant site par votre domaine. Veillez à inclure les caractères d'échappement.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

Une fois l'opération terminée, installez l'application mise à jour sur l'appareil ou publiez-la sur le Google Play Store ou sur l'une des autres plates-formes de distribution d'applications Android.

Indiquer à votre site Web l'existence de votre application Android

Ensuite, informez votre site Web de l'existence de votre application Android en ajoutant un fichier manifeste d'application Web à votre page. Le fichier manifeste doit inclure la propriété related_applications, un tableau qui fournit des informations sur votre application, y compris platform et id.

• platform doit être play
• id est l'ID du package Android.

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

Vérifier si votre application est installée

Enfin, appelez la fonction asynchrone navigator.getInstalledRelatedApps() pour vérifier si votre application Android est installée.

Vérifier si votre application Windows (UWP) est installée

Votre site Web peut vérifier si votre application Windows (créée à l'aide d'UWP) est installée.

Windows uniquement : Chrome 85 ou version ultérieure, Edge 85 ou version ultérieure

Indiquer à votre application Windows des informations sur votre site Web

Vous devrez mettre à jour votre application Windows pour définir la relation entre votre site Web et votre application Windows à l'aide des gestionnaires d'URI. Cela permet de vérifier que seul votre site Web peut vérifier si votre application Windows est installée.

Ajoutez l'enregistrement de l'extension Windows.appUriHandler au fichier manifeste de votre application Package.appxmanifest. Par exemple, si l'adresse de votre site Web est example.com, vous devez ajouter l'entrée suivante dans le fichier manifeste de votre application :

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Notez que vous devrez peut-être ajouter l'espace de noms uap3 à votre attribut <Package>.

Créez ensuite un fichier JSON (sans l'extension de fichier .json) nommé windows-app-web-link et indiquez le nom de famille du package de votre application. Placez ce fichier à la racine de votre serveur ou dans le répertoire /.well-known/. Vous trouverez le nom de la famille de packages dans la section "Packaging" du concepteur de fichier manifeste de l'application.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

Pour en savoir plus sur la configuration des gestionnaires d'URI, consultez Activer les applications pour les sites Web à l'aide des gestionnaires d'URI d'application.

Indiquer à votre site Web l'existence de votre application Windows

Ensuite, informez votre site Web de votre application Windows en ajoutant un fichier manifeste d'application Web à votre page. Le fichier manifeste doit inclure la propriété related_applications, un tableau qui fournit des informations sur votre application, y compris platform et id.

• platform doit être windows
• id correspond au nom de famille du package de votre application, auquel est ajoutée la valeur Id <Application> dans votre fichier Package.appxmanifest.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

Vérifier si votre application est installée

Enfin, appelez la fonction asynchrone navigator.getInstalledRelatedApps() pour vérifier si votre application Windows est installée.

Consultez cette démonstration.

Vérifier si votre application Web progressive est déjà installée (dans le champ d'application)

Votre PWA peut vérifier si elle est déjà installée. Dans ce cas, la page qui effectue la requête doit se trouver sur le même domaine et dans le champ d'application de votre PWA, tel que défini par le champ d'application dans le fichier manifeste de l'application Web.

Compatible avec :

Android : Chrome 84 ou version ultérieure

Ordinateur (Windows, macOS, Linux, ChromeOS) : Chrome 140 ou version ultérieure, Edge 140 ou version ultérieure

Parlez à votre PWA d'elle-même

Indiquez à votre PWA des informations sur elle-même en ajoutant une entrée related_applications dans le fichier manifeste de votre application Web.

• platform doit être webapp
• url est le chemin d'accès (qui peut être relatif) au fichier manifeste de l'application Web de votre PWA.
• id est l'ID de l'application Web déclaré dans le champ id du fichier manifeste de l'application Web ou calculé par le navigateur (obligatoire pour les ordinateurs, mais pas pour Android).

{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

Vérifier si votre PWA est installée

Enfin, appelez la fonction asynchrone navigator.getInstalledRelatedApps() depuis la portée de votre PWA pour vérifier si elle est installée. Si navigator.getInstalledRelatedApps() est appelé en dehors du champ d'application de votre PWA, il renverra []. Reportez-vous à la section suivante pour plus d'informations.

Vérifier si votre progressive web app est installée (hors champ d'application)

Votre site Web peut vérifier si votre PWA est installée, même si la page se trouve en dehors du champ d'application de votre PWA. Par exemple, une page de destination diffusée depuis /landing/ peut vérifier si la PWA diffusée depuis /pwa/ est installée, ou si votre page de destination est diffusée depuis www.example.com et votre PWA depuis app.example.com.

Compatible avec :

Android uniquement : Chrome 84 ou version ultérieure

Indiquer à votre PWA l'adresse de votre site Web

Vous devez d'abord ajouter des liens d'éléments numériques au serveur à partir duquel votre PWA est diffusée. Cela permet de définir la relation entre votre site Web et votre PWA, et de vérifier que seul votre site Web peut vérifier si votre PWA est installée.

Ajoutez un fichier assetlinks.json au répertoire /.well-known/ du domaine où se trouve la PWA, par exemple app.example.com. Dans la propriété site, indiquez le chemin d'accès complet au fichier manifeste de l'application Web qui effectuera la vérification (et non le fichier manifeste de l'application Web progressive).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

Ensuite, informez votre site Web de votre application PWA en ajoutant un fichier manifeste d'application Web à votre page. Le fichier manifeste doit inclure la propriété related_applications, un tableau qui fournit des informations sur votre PWA, y compris platform et url.

• platform doit être webapp
• url correspond au chemin d'accès complet au fichier manifeste de l'application Web de votre PWA.

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

Vérifier si votre PWA est installée

Enfin, appelez la fonction asynchrone navigator.getInstalledRelatedApps() pour vérifier si votre PWA est installée.

Vous avez d'autres questions ?

Vous avez d'autres questions ? Consultez le tag getInstalledRelatedApps sur StackOverflow pour voir si d'autres utilisateurs ont posé des questions similaires. Si ce n'est pas le cas, posez votre question et assurez-vous d'y ajouter le tag progressive-web-apps. Notre équipe surveille fréquemment ce tag et essaie de répondre à vos questions.

Commentaires

Avez-vous trouvé un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente de la spécification ?

• Signalez un bug sur https://new.crbug.com. Incluez autant de détails que possible, fournissez des instructions pour reproduire le bug et saisissez Mobile>WebAPKs dans la zone Composants.

Liens utiles

• Explication publique de l'API Get Installed Related Apps
• Brouillon de spécification
• Bug de suivi
• Entrée ChromeStatus.com
• Composant Blink : Mobile>WebAPKs

Merci

Merci tout particulièrement à Sunggook Chue de Microsoft pour son aide concernant les détails des tests des applications Windows, et à Rayan Kanso pour son aide concernant les détails de Chrome.