Configurer les associations de sites Web et les règles dynamiques

Pour prendre en charge les liens vers une application, vous devez créer un fichier JSON Digital Asset Links nommé assetlinks.json et le publier dans un emplacement connu de votre site Web. Ce fichier déclare publiquement les applications autorisées à gérer les liens pour votre domaine. Les appareils Android récupèrent ce fichier depuis votre serveur pour valider vos liens profonds.

Pour les liens dynamiques vers une application dans Android 15 ou version ultérieure, le fichier assetlinks.json est également l'endroit où vous définissez la configuration de vos règles dynamiques, telles que les outils de mise en correspondance des chemins d'accès pour les paramètres de chemin d'accès, de fragment et de requête. Les appareils Android équipés d'Android 15 (niveau d'API 35) ou version ultérieure sur lesquels les services Google sont installés récupèrent régulièrement le fichier et fusionnent votre configuration dynamique avec la configuration statique dans le fichier manifeste de l'application.

Ce guide explique comment préparer un assetlinks.json fichier et le publier sur votre site Web. Si vous préférez, vous pouvez générer un assetlinks.json fichier à partir de l'outil Play Deep Links ou de l'Assistant pour les liens vers des applications d'Android Studio. Pour en savoir plus, consultez Outils pour les développeurs pour les liens vers des applications.

Déclarer les associations de sites Web

Vous devez publier un fichier JSON Digital Asset Links sur votre site Web pour indiquer les applications Android associées au site Web et vérifier les intents d'URL de l'application. Le fichier JSON utilise les champs suivants pour identifier les applications associées :

package_name : ID de l'application déclaré dans le build.gradle fichier de l'application.
sha256_cert_fingerprints : empreintes SHA256 du certificat de signature de votre application. Vous pouvez utiliser la commande suivante pour générer l'empreinte à l'aide de l'outil Java keytool :

keytool -list -v -keystore my-release-key.keystore

Ce champ accepte plusieurs empreintes, qui peuvent être utilisées pour prendre en charge différentes versions de votre application, telles que les builds de débogage et de production. Si vous utilisez la signature d'application Play pour votre application, l'empreinte de certificat générée par l'exécution de keytool en local ne correspond généralement pas à celle qui se trouve sur les appareils des utilisateurs. Vous pouvez vérifier si vous utilisez la signature d'application Play pour votre application dans votre Play Console compte de développeur sous Release > Setup > App signing; si c'est le cas, vous trouverez également l'extrait JSON Digital Asset Links qui correspond à votre application sur la même page.

L'exemple de fichier assetlinks.json suivant accorde des droits d'ouverture de lien à une com.example application Android :

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Associer un site Web à plusieurs applications

Un site Web peut déclarer des associations avec plusieurs applications dans le même assetlinks.json fichier. La liste de fichiers suivante montre un exemple de fichier de déclaration qui déclare l'association avec deux applications, séparément, et réside à l'adresse https://www.example.com/.well-known/assetlinks.json :

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Différentes applications peuvent gérer des liens vers différentes ressources sous le même hôte Web. Par exemple, l'application 1 peut déclarer un filtre d'intent pour https://example.com/articles, et l'application 2 peut déclarer un filtre d'intent pour https://example.com/videos.

Associer plusieurs sites Web à une seule application

Plusieurs sites Web peuvent déclarer des associations avec la même application dans leurs fichiers respectifs assetlinks.json. Les listes de fichiers suivantes montrent un exemple de déclaration de l'association d'example.com et d'example.net avec l'application 1. La première liste montre l'association d'example.com avec l'application 1 :

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

La liste suivante montre l'association d'example.net avec l'application 1. Seul l' emplacement où ces fichiers sont hébergés est différent (.com et .net) :

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Configurer des règles dynamiques

Les liens dynamiques vers une application dans Android 15 ou version ultérieure vous permettent d'utiliser des règles de mise en correspondance des liens profonds côté serveur qui fonctionnent avec les règles que vous avez définies de manière statique dans le fichier manifeste de votre application. Votre fichier assetlinks.json est l'endroit où vous définissez les règles dynamiques. L'inclusion de ces règles est facultative.

Les appareils Android équipés d'Android 15 (niveau d'API 35) ou version ultérieure sur lesquels les services Google sont installés récupèrent régulièrement ce fichier depuis votre serveur et fusionnent votre configuration de règles dynamiques avec la configuration statique dans le fichier manifeste de l'application. Voici un exemple de fichier assetlinks.json avec des règles dynamiques :

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Points clés concernant le code

Les liens dynamiques vers une application ajoutent une nouvelle extension de relation Digital Asset Links appelée dynamic_app_link_components, qui vous permet de configurer vos règles dynamiques.
Les règles dynamiques peuvent inclure des outils de mise en correspondance des chemins d'accès pour les paramètres de chemin d'accès, de fragment et de requête.
Vous pouvez également marquer n'importe quel outil de mise en correspondance des chemins d'accès comme exclu, afin que les URL correspondantes n'ouvrent pas votre application.
Cet exemple montre des outils de mise en correspondance pour les paramètres de chemin d'accès ("/"), de fragment ("#"), de requête ("?") et exclus ("exclude").
Si l'un des champs du fichier est mal formé ou vide, Android ignore les règles dynamiques et l'appareil revient aux règles définies de manière statique dans le fichier manifeste de l'application.

Les règles dynamiques ne peuvent spécifier que des règles qui s'appliquent dans le champ d'application des domaines que vous déclarez dans le fichier manifeste de votre application. (voir ci-dessous).

Déclarer des règles dynamiques

Les liens dynamiques vers une application sont compatibles avec une nouvelle dynamic_app_link_components relation extension, qui contient un tableau d'objets de règles. Chaque règle est définie à l'aide d' outils de mise en correspondance des chemins d'accès pour les chemins d'accès, les fragments et les paramètres de requête qui ouvriront votre application. Les outils de mise en correspondance peuvent également être exclus individuellement afin qu'ils n'ouvrent pas votre application. Tous ces éléments sont facultatifs.

Mise en correspondance des chemins d'accès
- Clé : "/"
- Valeur : chaîne unique, expression de mise en correspondance pour le chemin d'accès de l'URL
Mise en correspondance des fragments
- Clé : "#"
- Valeur : chaîne unique, expression de mise en correspondance pour le fragment d'URL
Mise en correspondance des paramètres de requête
- Clé : "?"
- Valeur : dictionnaire permettant de mettre en correspondance les paires clé/valeur dans les paramètres de requête de l'URL.
- Par exemple, le dictionnaire {"?", {"dl": "*", "in_app":"true"} correspondra à la chaîne de requête "?in_app=true&dl=abc".
- L'ordre des paires clé/valeur dans le dictionnaire n'a pas besoin de correspondre à l' ordre des paires dans la chaîne de requête. De plus, le dictionnaire n'a pas besoin de correspondre à toutes les paires clé/valeur de la chaîne de requête, mais une correspondance doit être trouvée pour chaque entrée de dictionnaire.
- Par exemple, le dictionnaire correspondrait également à la chaîne de requête "?lang=en&in_app=true&tz=pst&dl=abc", mais pas à la chaîne de requête "?lang=en&tz=pst&dl=abc"
Exclus
- Clé : "exclude"
- Valeur : valeur booléenne facultative pour chaque règle définie dans dynamic_app_link_components (voir l'exemple).

Vous pouvez utiliser ces caractères spéciaux dans les outils de mise en correspondance des chemins d'accès :

« * » correspond à zéro caractère ou plus jusqu'à ce que le caractère suivant le caractère générique du modèle soit trouvé dans la chaîne correspondante.
"?" correspond à n'importe quel caractère unique.
"?*" correspond à un caractère ou plus.

Il n'existe aucune autre restriction de caractère pour les valeurs.

Ordonner les règles dynamiques

L'ordre dans lequel les règles sont déclarées est important. Android évalue chaque règle dans l'ordre jusqu'à ce qu'il trouve une correspondance.

L'exemple suivant montre comment l'ordre peut affecter la gestion. La première règle correspond à tous les chemins d'accès ("*"), mais exclut les correspondances (exclude: true), ce qui signifie qu'elle empêche toutes les URL d'ouvrir l'application. Dans ce cas, la deuxième règle qui autorise "/path1" ne sera jamais évaluée.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

Toutefois, dans l'exemple suivant, la règle "/path1" est déclarée en premier. Elle sera donc évaluée en premier et ouvrira l'application pour une URL correspondant à "/path1". La deuxième règle, qui empêche toutes les URL d'ouvrir l'application, sera évaluée en deuxième, mais uniquement si la première règle ne correspond pas.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Si aucune correspondance n'est trouvée dans la liste des composants déclarés, l'URL n'ouvrira pas l'application. Dans l'exemple suivant, aucun des chemins d'accès ne correspond à « /path3 ». L'appareil traitera donc ce chemin d'accès comme exclu.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Ce comportement est important si vous souhaitez que dynamic_app_link_components n'exclue que certaines parties d'URL, mais autorise toutes les autres. Dans l'exemple suivant, si vous omettez la règle finale pour autoriser tous les chemins d'accès restants, toutes les URL seront exclues de l'application.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Définir correctement le champ d'application de vos règles dynamiques

Lorsque vous définissez vos règles côté serveur pour les utiliser avec les liens dynamiques vers une application dans Android 15 ou version ultérieure, il est important de les définir de manière appropriée afin qu'elles fonctionnent avec les filtres d'intent statiques déclarés dans le fichier manifeste de votre application et les complètent.

Les règles dynamiques déclarées dans le fichier assetlinks.json ne peuvent spécifier que des règles pour les hôtes que vous déclarez dans le fichier AndroidManifest.xml de votre application. Les règles dynamiques règles ne peuvent pas étendre le champ d'application des règles d'URL que vous déclarez de manière statique dans le fichier manifeste de votre application.

Pour cette raison, nous vous recommandons d'utiliser cette approche pour vos règles dynamiques et statiques :

Dans le fichier manifeste de votre application, définissez des règles avec le champ d'application le plus large possible, par exemple en ne déclarant que le schéma et le domaine.
Appuyez-vous sur les règles dynamiques côté serveur pour affiner davantage, par exemple le routage au niveau du chemin d'accès.

Avec cette configuration idéale, vous pourrez ajouter dynamiquement de nouveaux chemins d'accès aux liens vers une application dans le fichier assetlinks.json si nécessaire, en sachant qu'ils s'inscriront dans le champ d'application large que vous avez défini dans le fichier manifeste de l'application.

Déclarer dynamic_app_link_components une seule fois

Pour une gestion appropriée de vos règles, ne déclarez qu'un seul objet dynamic_app_link_components dans les instructions d'un site, d'une relation et d'une application donnés.

Recherchez plusieurs instructions pour le même site, la même relation et la même application, qui déclarent un objet dynamic_app_link_components.
Recherchez plusieurs objets dynamic_app_link_components déclarés dans une seule instruction.

Dans ces cas, Android ne garantit pas la configuration de règles dynamiques qui sera utilisée.

Compatibilité des règles dynamiques avec les configurations de liens vers une application antérieures

Si vous êtes déjà compatible avec les liens vers une application, vous pouvez ajouter la compatibilité avec les liens dynamiques vers une application directement dans votre fichier assetlinks.json existant. Les champs de relation permettant de vérifier vos liens vers une application restent les mêmes, et vous pouvez ajouter les nouveaux champs d'extension de relation pour les règles dynamiques sans aucune autre modification.

Les appareils Android équipés d'Android 14 (niveau d'API 34 ou version antérieure) ignorent les nouveaux champs d'extension de relation pour les règles dynamiques, tandis que les appareils équipés d'Android 15 ou version ultérieure fusionnent ces règles avec celles définies dans votre fichier manifeste.

Publier le fichier de validation JSON

Vous devez publier votre fichier de validation JSON à l'emplacement suivant :

https://domain.name/.well-known/assetlinks.json

Assurez-vous des points suivants :

Le fichier assetlinks.json est diffusé avec le type de contenu application/json.
Le fichier assetlinks.json doit être accessible via une connexion HTTPS, que les filtres d'intent de votre application déclarent HTTPS comme schéma de données ou non.
Le fichier assetlinks.json doit être accessible sans aucune redirection (pas de redirection 301 ni 302).
Si les liens vers votre application sont compatibles avec plusieurs domaines hôtes, vous devez publier le assetlinks.json fichier sur chaque domaine. Consultez la section Compatibilité des liens vers une application pour plusieurs hôtes.
Ne publiez pas votre application avec des URL de test dans le fichier manifeste qui ne sont pas accessibles au public (par exemple, celles qui ne sont accessibles qu'avec un VPN). Dans ce cas, vous pouvez configurer des variantes de compilation pour générer un fichier manifeste différent pour les builds de développement.

Consultez les guides associés suivants :