Ajouter des filtres d'intent pour les liens d'application

Les liens vers une application sont des liens profonds qui utilisent le schéma HTTP ou HTTPS et dont Android a vérifié qu'ils étaient associés à votre site Web. Pour enregistrer votre application afin qu'elle gère les liens d'application, procédez comme suit :

Ajoutez un ou plusieurs filtres d'intent au fichier manifeste de votre application pour spécifier le domaine ou les URL de votre site Web.
Ajoutez autoVerify="true"attribute aux éléments du filtre d'intent. Cela indique au système qu'il doit essayer de valider le ou les domaines de schéma et d'hôte par rapport à la configuration assetlinks.json de votre site Web.
Déclarez les associations de sites Web.

Voici un exemple de déclaration App Link avec des schémas et des hôtes, ainsi que autoVerify="true :

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

Points clés concernant le code

AutoVerify : l'attribut android:autoVerify="true" est obligatoire pour les liens d'application. Il indique au système qu'il doit tenter de valider l'association entre votre application et les schémas et domaines spécifiés dans les balises <data>. Nous vous recommandons d'ajouter autoVerify="true à chaque filtre d'intent que vous souhaitez pouvoir valider.
Éléments de données : chaque filtre d'intent App Links doit inclure un ou plusieurs éléments <data> qui spécifient les schémas et les formats d'hôte correspondant au domaine de votre site Web validable.
Schémas : le filtre d'intent doit inclure des éléments <data> pour les schémas http et https.
Hôtes : vous pouvez éventuellement ajouter des éléments <data> pour établir une correspondance avec un ou plusieurs hôtes. Utilisez un caractère générique (*) pour associer plusieurs sous-domaines (par exemple, *.example.com). Le système tentera de valider chaque hôte par rapport à votre fichier assetlinks.json sur votre site Web. Notez que tout routage au niveau du chemin d'accès doit être géré par le fichier assetlinks.json (voir la section sur les bonnes pratiques ci-dessous).
Plusieurs hôtes : si vous déclarez plusieurs domaines hôtes, le système (sur Android 12 ou version ultérieure) tente de valider chacun d'eux. Si un hôte est validé, l'application devient le gestionnaire par défaut des liens provenant de cet hôte validé. Sur Android 11 et versions antérieures, la validation échoue si un seul hôte ne peut pas être validé.
Plusieurs filtres d'intent : il est important de créer des filtres distincts lorsque vous souhaitez déclarer des URL uniques (par exemple, une combinaison spécifique de schéma et d'hôte), car plusieurs éléments <data> dans le même filtre d'intent sont fusionnés pour tenir compte de toutes les variantes de leurs attributs combinés.

Points à prendre en compte pour les règles de filtrage des fichiers manifestes

Si vous configurez des filtres à utiliser avec les liens dynamiques vers une application dans Android 15 et versions ultérieures, il est important de se rappeler que les règles dynamiques déclarées dans le fichier assetlinks.json côté serveur 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 :

Dans le fichier manifeste de votre application, définissez le champ d'application le plus large possible, par exemple en déclarant uniquement le schéma et le domaine.
S'appuyer sur les règles assetlinks.json 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 App Links 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.

Prise en charge des liens d'application pour plusieurs hôtes

Le système doit pouvoir valider l'hôte spécifié dans les éléments de données des filtres d'intent d'URL de l'application par rapport aux fichiers Digital Asset Links hébergés sur les domaines Web respectifs de ce filtre d'intent. Si la validation échoue, le système revient à son comportement standard pour résoudre l'intention, comme décrit dans Créer des liens profonds vers le contenu d'une application. Toutefois, l'application peut toujours être validée en tant que gestionnaire par défaut pour l'un des modèles d'URL définis dans les autres filtres d'intent de l'application.

Par exemple, une application avec les filtres d'intent suivants ne serait validée que pour https://www.example.com si un fichier assetlinks.json était trouvé à l'adresse https://www.example.com/.well-known/assetlinks.json, mais pas à l'adresse https://www.example.net/.well-known/assetlinks.json :

<application>

  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

Associer des applications à plusieurs sous-domaines

Le protocole Digital Asset Links traite les sous-domaines de vos filtres d'intent comme des hôtes uniques et distincts. Par conséquent, si votre filtre d'intentions liste plusieurs hôtes avec des sous-domaines différents, vous devez publier un fichier assetlinks.json valide sur chaque domaine. Par exemple, le filtre d'intent suivant inclut www.example.com et mobile.example.com comme hôtes d'URL d'intent acceptés. Par conséquent, une valeur assetlinks.json valide doit être publiée à la fois sur https://www.example.com/.well-known/assetlinks.json et https://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

Si vous déclarez votre nom d'hôte avec un caractère générique (tel que *.example.com), vous devez publier votre fichier assetlinks.json au niveau du nom d'hôte racine (example.com). Par exemple, une application avec le filtre d'intent suivant passera la validation pour n'importe quel sous-nom de example.com (tel que foo.example.com) tant que le fichier assetlinks.json est publié sur https://example.com/.well-known/assetlinks.json :

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Vérifier si plusieurs applications sont associées au même domaine

Si vous publiez plusieurs applications associées au même domaine, elles peuvent toutes être validées. Toutefois, si les applications peuvent résoudre exactement le même hôte et chemin de domaine, comme cela peut être le cas avec les versions Lite et complètes d'une application, seule l'application installée le plus récemment peut résoudre les intents Web pour ce domaine.

Dans ce cas, recherchez d'éventuelles applications conflictuelles sur l'appareil de l'utilisateur, à condition que vous disposiez de la visibilité du package nécessaire. Ensuite, dans votre application, affichez une boîte de dialogue de sélection personnalisée contenant les résultats de l'appel de queryIntentActivities. L'utilisateur peut sélectionner l'application de son choix dans la liste des applications correspondantes qui s'affiche dans la boîte de dialogue.

Rétrocompatibilité des liens dynamiques vers une application pour Android 14 et versions antérieures

Les fonctionnalités de liens d'application dynamiques, y compris les règles de correspondance avancées dans assetlinks.json et l'utilisation de <uri-relative-filter-group>, ne sont entièrement prises en charge que sur Android 15 (niveau d'API 35) et versions ultérieures.

Sur Android 14 (niveau d'API 34) et versions antérieures, le système ne tient compte que des éléments scheme et host déclarés dans les éléments <data> du fichier manifeste pour la validation des liens vers l'application. Les règles, exclusions et mises à jour dynamiques spécifiques aux chemins d'accès à partir d'assetlinks.json ne sont pas appliquées.

Cela signifie que si votre fichier manifeste ne spécifie que scheme et host, votre application peut capturer de manière inattendue tous les chemins du domaine validé sur Android 14 et versions antérieures, quelles que soient les règles spécifiques au chemin définies dans votre assetlinks.json pour Android 15 et versions ultérieures.

Stratégie de remplacement pour les versions d'Android antérieures à configurer sans liens profonds

Pour empêcher votre application de gérer tous les liens d'un domaine sur Android 14 et versions antérieures lorsque vous prévoyez d'utiliser les liens d'application dynamiques pour des chemins plus spécifiques sur Android 15 et versions ultérieures, incluez un chemin non correspondant dans le filtre d'intent de votre fichier manifeste. Ajoutez un élément <data> avec un attribut android:path qui ne sera probablement jamais un chemin d'accès valide pour vos liens. Cela garantit que le filtre d'intent ne correspond pas à tous les chemins d'accès dans les versions antérieures.

Exemple :

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

En ajoutant <data android:path="/no_match_for_older_android_versions" />, vous vous assurez que sur Android 14 et les versions antérieures, ce filtre d'intent ne correspond à aucun lien entrant, tout en permettant de valider le domaine pour l'utiliser avec les liens dynamiques vers une application sur Android 15 et les versions ultérieures, en fonction des règles de correspondance avancées de vos règles assetlinks.json.

Migrer des liens vers une application existants

Si vous avez déjà des liens d'application avec des règles de chemin d'accès spécifiques (telles que android:pathPrefix) dans votre fichier manifeste et que vous souhaitez commencer à utiliser des liens d'application dynamiques sur Android 15 et versions ultérieures, vous pouvez ajouter l'élément <uri-relative-filter-group> directement à vos filtres d'intent existants.

Étant donné qu'Android 14 et les versions antérieures ignorent l'élément <uri-relative-filter-group>, vos liens d'application existants continueront de fonctionner exactement comme ils le font actuellement sur les appareils équipés de versions antérieures d'Android.

Toutefois, vous devez examiner attentivement la façon dont Android 15 et les versions ultérieures évaluent la configuration "mixte" :

Filtrage à deux niveaux : sur Android 15 et versions ultérieures, le système évalue les filtres d'intent en tant qu'union. Une URL réussit la vérification du fichier manifeste si elle satisfait à vos anciennes balises <data> statiques ou aux règles générales de votre <uri-relative-filter-group>. Une fois que l'URL a passé cette vérification initiale du fichier manifeste, le système applique les règles dynamiques définies dans votre fichier assetlinks.json comme deuxième niveau de filtrage précis. Cela signifie que les règles JSON côté serveur déterminent en fin de compte quelles URL correspondantes ouvrent réellement l'application.

Exemple de configuration hybride :

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>