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 l'association à votre site Web est validée par Android. Pour vous inscrire et gérer les liens vers une 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 le autoVerify="true"attribute aux éléments de filtre d'intent. Cela indique au système qu'il doit tenter de valider le schéma et le ou les domaines hôtes par rapport à la configuration assetlinks.json de votre site Web.
Déclarez les associations de sites Web.

Voici un exemple de déclaration de lien vers une application 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 essentiels concernant le code

AutoVerify : l'attribut android:autoVerify="true" est obligatoire pour les liens vers une 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 <data> balises. 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 de lien vers une application doit inclure un ou plusieurs <data> éléments qui spécifient les schémas et les formats d'hôte correspondant au domaine de votre site Web pouvant être validé.
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 faire correspondre un ou plusieurs hôtes. Utilisez un caractère générique (*) pour faire correspondre 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 au moins un 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 prendre en compte toutes les variantes de leurs attributs combinés.

Considérations concernant les règles de filtre de fichier manifeste

Si vous configurez des filtres à utiliser avec des liens dynamiques vers une application sous Android 15 ou version ultérieure, il est important de vous rappeler que les règles dynamiques déclarées dans le fichier assetlinks.json côté serveur ne peuvent pas étendre la portée 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 :

Dans le fichier manifeste de votre application, définissez la portée la plus large possible, par exemple en déclarant uniquement le schéma et le domaine.
Utilisez les règles assetlinks.json 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 la portée étendue que vous avez définie dans le fichier manifeste d'application.

Compatibilité avec les liens vers une 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'intent, 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>

Compatibilité avec les liens vers une application pour 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'intent répertorie 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. Un fichier assetlinks.json valide doit donc être publié à la fois à l'adresse https://www.example.com/.well-known/assetlinks.json et à l'adresse 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 assetlinks.json fichier au niveau du root hostname (example.com). Par exemple, une application avec le filtre d'intent suivant sera validée pour n'importe quel sous-nom de example.com (tel que foo.example.com) à condition que le assetlinks.json fichier soit publié à 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 le même chemin d'accès de domaine, comme cela peut être le cas avec les versions Lite et complète d'une application, seule l'application installée le plus récemment peut résoudre les intents Web pour ce domaine.

Dans ce cas, vérifiez si des applications potentiellement conflictuelles sont présentes sur l'appareil de l'utilisateur, à condition que vous disposiez de la visibilité de package nécessaire. Ensuite, dans votre application, affichez une boîte de dialogue de sélecteur personnalisée contenant les résultats de l'appel 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 dynamiques vers une application, y compris les règles de correspondance avancées dans assetlinks.json et l'utilisation de <uri-relative-filter-group>, ne sont entièrement compatibles qu'avec Android 15 (niveau d'API 35) et versions ultérieures.

Sous Android 14 (niveau d'API 34) et versions antérieures, le système ne prend en compte que le scheme et host déclarés dans les éléments <data> de votre fichier manifeste pour la validation des liens vers une application. Les règles, exclusions et mises à jour dynamiques spécifiques au chemin d'accès provenant 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 d'accès pour le domaine validé sous Android 14 et versions antérieures, quelles que soient les règles spécifiques au chemin d'accès 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 sous Android 14 et versions antérieures lorsque vous prévoyez d'utiliser des liens dynamiques vers une application pour des chemins d'accès plus spécifiques sous Android 15 et versions ultérieures, incluez un chemin d'accès 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 sur 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 sous Android 14 et versions antérieures, ce filtre d'intent ne correspond à aucun lien entrant, tout en permettant au domaine d'être validé pour une utilisation avec des liens dynamiques vers une application sous Android 15 et versions ultérieures en fonction des règles de correspondance avancées de vos règles assetlinks.json.

Migration des liens vers une application existants

Si vous disposez déjà de liens vers une 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 dynamiques vers une application sous 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 versions antérieures ignorent l'élément <uri-relative-filter-group>, vos liens vers une application existants continuent de fonctionner exactement comme ils le font actuellement sur les appareils exécutant des versions antérieures d'Android.

Toutefois, vous devez examiner attentivement comment Android 15 et versions ultérieures évaluent la configuration "mixte" :

Filtrage à deux niveaux : sous 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 les règles générales de votre <uri-relative-filter-group>. Une fois que l'URL a réussi cette vérification initiale du fichier manifeste, le système applique les règles dynamiques définies dans votre fichier assetlinks.json en tant que deuxième niveau de filtrage précis. Cela signifie que les règles JSON côté serveur déterminent en définitive 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>