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

Pour prendre en charge les liens d'application, vous devez créer un fichier JSON Digital Asset Links appelé assetlinks.json et le publier à un emplacement connu sur votre site Web. Ce fichier indique 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, comme les correspondances de modèles pour les paramètres de chemin d'accès, de fragment et de requête. Les appareils Android exécutant 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 fichier assetlinks.json et le publier sur votre site Web. Si vous préférez, vous pouvez générer un fichier assetlinks.json à partir de l'outil Play Deep Links ou de l'assistant Android Studio App Links. Pour en savoir plus, consultez Outils pour les développeurs de liens d'application.

Déclarer des 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 valider 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 fichier build.gradle 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 digitale à l'aide de l'outil Java keytool :

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

  • Ce champ accepte plusieurs empreintes digitales, 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. Pour vérifier si vous utilisez la signature d'application Play pour votre application, accédez à votre compte de développeur Play Console 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 les droits d'ouverture de liens à une application Android com.example :

[{
  "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 fichier assetlinks.json. 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 qui 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 les 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 assetlinks.json respectifs. Les listes de fichiers suivantes montrent comment déclarer l'association d'example.com et example.net avec app1. La première liste montre l'association d'example.com avec app1 :

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 de example.net avec app1. 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 vers votre application dynamiques dans Android 15 et versions ultérieures vous permettent d'utiliser des règles de correspondance de 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 vous permet de définir des règles dynamiques. Cette information est facultative.

Les appareils Android exécutant 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 la configuration de vos 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 correspondance de modèles pour les paramètres de chemin d'accès, de fragment et de requête.
  • Vous pouvez également marquer un outil de mise en correspondance de formats comme exclu afin que les URL correspondantes n'ouvrent pas votre application.
  • Cet exemple montre des exemples de mise en correspondance pour le chemin d'accès ("/"), le fragment ("#") et les paramètres de requête ("?"), ainsi que les outils de mise en correspondance 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 d'application dynamiques sont compatibles avec une nouvelle extension de relation dynamic_app_link_components, qui contient un tableau d'objets de règles. Chaque règle est définie à l'aide de correspondances de modèles pour les chemins, les fragments et les paramètres de requête qui ouvriront votre application. Les correspondances peuvent également être exclues individuellement afin qu'elles n'ouvrent pas votre application. Tous ces éléments sont facultatifs.

  • Mise en correspondance des chemins d'accès
    • Touche : "/"
    • Valeur : chaîne unique, expression de correspondance pour le chemin d'URL
  • Correspondance de fragments
    • Clé : "#"
    • Valeur : chaîne unique, expression correspondante pour le fragment d'URL
  • Correspondance des paramètres de requête
    • Clé : "?"
    • Valeur : dictionnaire permettant de faire correspondre les paires clé/valeur dans les paramètres de requête d'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 ne doit pas nécessairement 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 du 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".
  • Exclue
    • Clé : "exclude"
    • Valeur : valeur booléenne facultative (true/false) pour chaque règle définie dans dynamic_app_link_components (voir l'exemple).

Vous pouvez utiliser les caractères spéciaux suivants dans les comparateurs de modèles :

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

Aucune autre restriction de caractères ne s'applique aux valeurs.

Organiser 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 le traitement. La première règle correspond à tous les chemins ("*") mais exclut les correspondances (exclude: true), ce qui signifie qu'elle empêche l'ouverture de l'application pour toutes les URL. 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 l'ouverture de l'application pour toutes les URL, sera évaluée en deuxième, mais uniquement si la première règle ne correspond pas.

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 à utiliser avec les liens d'application dynamiques dans Android 15 et versions ultérieures, 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 des règles que pour les hôtes que vous déclarez dans le fichier AndroidManifest.xml de votre application. Les règles dynamiques 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.

C'est pourquoi 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 la portée la plus large possible, par exemple en déclarant uniquement le schéma et le domaine.
  • S'appuyer sur les règles dynamiques côté serveur pour affiner davantage le routage, par exemple au niveau du chemin d'accès.

Avec cette configuration idéale, vous pourrez ajouter dynamiquement de nouveaux chemins de liens vers une application dans le fichier assetlinks.json selon vos besoins, en sachant qu'ils s'inscriront dans le champ d'application étendu que vous avez défini dans le fichier manifeste de l'application.

Pour que vos règles soient traitées correctement, ne déclarez qu'un seul objet dynamic_app_link_components dans les instructions pour un site, une relation et une application donnés.

  • Recherchez plusieurs déclarations 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 même instruction.

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

Compatibilité des règles dynamiques avec les configurations précédentes des liens vers une application

Si vous gérez déjà les liens d'application, vous pouvez ajouter la prise en charge des liens d'application dynamiques directement dans votre fichier assetlinks.json existant. Les champs de relation pour valider vos liens d'application restent les mêmes. Vous pouvez ajouter les nouveaux champs d'extension de relation pour les règles dynamiques sans apporter d'autres modifications.

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 (redirections 301 ou 302).
  • Si vos liens d'application sont compatibles avec plusieurs domaines hôtes, vous devez publier le fichier assetlinks.json sur chaque domaine. Consultez Prise en charge de l'association d'applications 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, une solution consiste à configurer des variantes de compilation pour générer un fichier manifeste différent pour les versions de développement.

Consultez les guides associés suivants :