Valider les liens vers une application

Lorsque android:autoVerify="true" est présent dans au moins l'un des filtres d'intent de votre application, l'installation de votre application sur un appareil exécutant Android 6.0 (niveau d'API 23) ou version ultérieure entraîne la vérification automatique par le système des hôtes associés aux URL dans les filtres d'intent de votre application. Sur Android 12 et versions ultérieures, vous pouvez également appeler manuellement la procédure de validation pour tester la logique de validation.

Validation automatique

La validation automatique du système implique les éléments suivants :

1. Le système inspecte tous les filtres d'intent qui incluent l'un des éléments suivants :
   • Action : android.intent.action.VIEW
   • Catégories : android.intent.category.BROWSABLE et android.intent.category.DEFAULT
   • Schéma de données : http ou https
2. Pour chaque nom d'hôte unique trouvé dans les filtres d'intent ci-dessus, Android interroge les sites Web correspondants pour le fichier Digital Asset Links à l'adresse https:///.well-known/assetlinks.json.

Remarque : Sur Android 11 (niveau d'API 30) et versions antérieures, le système définit votre application comme gestionnaire par défaut pour les formats d'URL spécifiés uniquement s'il trouve un fichier Digital Asset Links correspondant pour tous les hôtes du fichier manifeste.

Une fois que vous avez confirmé la liste des sites Web à associer à votre application et que vous avez vérifié que le fichier JSON hébergé est valide, installez l'application sur votre appareil. Patientez au moins 20 secondes pour que la procédure de validation asynchrone se termine. Utilisez la commande suivante pour vérifier si le système a validé votre application et défini les règles de gestion des liens appropriées :

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Validation manuelle

À partir d'Android 12, vous pouvez appeler manuellement la validation de domaine pour une application installée sur un appareil. Vous pouvez effectuer ce processus, que votre application cible ou non Android 12.

Établir une connexion Internet

Pour valider le domaine, votre appareil de test doit être connecté à Internet.

Prendre en charge la nouvelle procédure de validation de domaine

Si votre application cible Android 12 ou version ultérieure, le système utilise automatiquement la procédure de validation de domaine mise à jour.

Sinon, vous pouvez activer manuellement la procédure de validation mise à jour. Pour ce faire, exécutez la commande suivante dans une fenêtre de terminal :

adb shell am compat enable 175408749 PACKAGE_NAME

Réinitialiser l'état des liens vers l'application Android sur un appareil

Avant d'appeler manuellement la validation du domaine sur un appareil, vous devez réinitialiser l'état des liens vers l'application Android sur l'appareil de test. Pour ce faire, exécutez la commande suivante dans une fenêtre de terminal :

adb shell pm set-app-links --package PACKAGE_NAME 0 all

Cette commande place l'appareil dans le même état qu'avant que l'utilisateur ne choisisse des applications par défaut pour les domaines.

Lancer la procédure de validation du domaine

Une fois que vous avez réinitialisé l'état des liens vers l'application Android sur un appareil, vous pouvez effectuer la vérification elle-même. Pour ce faire, exécutez la commande suivante dans une fenêtre de terminal :

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Remarque : Avant d'examiner les résultats de cette commande, patientez quelques minutes pour que l'agent de validation termine les demandes liées à la validation du domaine.

Examiner les résultats de la validation

Après avoir laissé le temps à l'agent de validation de terminer ses requêtes, examinez les résultats de la validation. Pour ce faire, exécutez la commande suivante :

adb shell pm get-app-links PACKAGE_NAME

Le résultat de cette commande ressemble à ceci :

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

Les domaines qui sont validés ont un état de validation verified. Tout autre état indique que la validation du domaine n'a pas pu être effectuée. En particulier, un état none indique que l'agent de validation n'a peut-être pas encore terminé le processus de validation.

La liste suivante indique les valeurs de retour possibles que la validation de domaine peut renvoyer pour un domaine donné :

none

 : rien n'a été enregistré pour ce domaine. Patientez quelques minutes de plus pour que l'agent de validation termine les requêtes liées à la validation du domaine, puis relancez la procédure de validation du domaine.

verified

Le domaine a bien été validé pour l'application déclarante.

approved

Le domaine a été approuvé de force, généralement en exécutant une commande shell.

denied

L'accès au domaine a été refusé de force, généralement en exécutant une commande shell.

migrated

Le système a conservé le résultat d'un processus précédent qui utilisait l'ancienne validation de domaine.

restored

Le domaine a été approuvé après que l'utilisateur a restauré les données. Le domaine est supposé avoir été validé précédemment.

legacy_failure

Le domaine a été refusé par un ancien outil de validation. La raison spécifique de l'échec est inconnue.

system_configured

Le domaine a été approuvé automatiquement par la configuration de l'appareil.

Code d'erreur 1024 ou supérieur

Code d'erreur personnalisé spécifique au vérificateur de l'appareil.

Vérifiez que vous avez établi une connexion réseau, puis relancez la procédure de validation du domaine.

Demander à l'utilisateur d'associer votre application à un domaine

Une autre façon d'obtenir l'approbation de votre application pour un domaine consiste à demander à l'utilisateur d'associer votre application à ce domaine.

Remarque : Sur un appareil donné, une seule application à la fois peut être associée à un domaine spécifique. Si une autre application est déjà validée pour le domaine, l'utilisateur doit d'abord dissocier cette autre application du domaine avant de pouvoir associer votre application au domaine.

Vérifier si votre application est déjà approuvée pour le domaine

Avant d'inviter l'utilisateur, vérifiez si votre application est le gestionnaire par défaut des domaines que vous définissez dans vos éléments <intent-filter>. Vous pouvez interroger l'état d'approbation à l'aide de l'une des méthodes suivantes :

• L'API DomainVerificationManager (au moment de l'exécution).
• Un programme de ligne de commande (pendant les tests).

DomainVerificationManager

L'extrait de code suivant montre comment utiliser l'API DomainVerificationManager :

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the user
// has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user has
        // associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Programme en ligne de commande

Lorsque vous testez votre application pendant le développement, vous pouvez exécuter la commande suivante pour interroger l'état de validation des domaines appartenant à votre organisation :

adb shell pm get-app-links --user cur PACKAGE_NAME

Dans l'exemple de résultat suivant, même si la validation de l'application pour le domaine "example.org" a échoué, l'utilisateur 0 a approuvé manuellement l'application dans les paramètres système, et aucun autre package n'est validé pour ce domaine.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Vous pouvez également utiliser des commandes shell pour simuler le processus par lequel l'utilisateur sélectionne l'application associée à un domaine donné. Pour obtenir une explication complète de ces commandes, consultez le résultat de adb shell pm.

Remarque : Le système ne peut associer qu'une seule application à la fois à un domaine, même lorsque vous utilisez des commandes shell. Certains cas particuliers, comme l'installation simultanée de deux variantes d'application, nécessitent un traitement spécial pour ouvrir un lien Web donné dans l'application souhaitée.

Fournir du contexte pour la demande

Avant de demander l'approbation du domaine, fournissez un contexte à l'utilisateur. Par exemple, vous pouvez lui présenter un écran de démarrage, une boîte de dialogue ou un élément d'interface utilisateur similaire qui lui explique pourquoi votre application doit être le gestionnaire par défaut pour un domaine particulier.

Envoyer la demande

Une fois que l'utilisateur a compris ce que votre application lui demande de faire, faites la demande. Pour ce faire, appelez un intent qui inclut l'action d'intent ACTION_APP_OPEN_BY_DEFAULT_SETTINGS et une chaîne de données correspondant à package:com.example.pkg pour l'application cible, comme indiqué dans l'extrait de code suivant :

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Lorsque l'intention est appelée, les utilisateurs voient un écran de paramètres intitulé Ouvrir par défaut. Cet écran contient une option appelée Ouvrir les liens compatibles, comme illustré à la figure 1.

Lorsque l'utilisateur active l'option Ouvrir les liens compatibles, un ensemble de cases à cocher s'affiche sous la section Liens à ouvrir dans cette application. À partir de là, les utilisateurs peuvent sélectionner les domaines qu'ils souhaitent associer à votre application. Ils peuvent également sélectionner Ajouter un lien pour ajouter des domaines, comme illustré sur la figure 2. Lorsque les utilisateurs sélectionnent ensuite un lien dans les domaines qu'ils ajoutent, il s'ouvre automatiquement dans votre application.

Figure 1. Écran des paramètres système où les utilisateurs peuvent choisir les liens qui s'ouvrent par défaut dans votre application.

Figure 2. Boîte de dialogue permettant aux utilisateurs de choisir des domaines supplémentaires à associer à votre application.

Ouvrir des domaines dans votre application que celle-ci ne peut pas valider

La fonction principale de votre application peut être d'ouvrir des liens en tant que tiers, sans pouvoir valider ses domaines gérés. Si tel est le cas, expliquez aux utilisateurs que, lorsqu'ils sélectionnent un lien Web, ils ne peuvent pas choisir entre une application propriétaire et votre application (tierce). Les utilisateurs doivent associer manuellement les domaines à votre application tierce.

En outre, envisagez d'introduire une boîte de dialogue ou une activité de trampoline qui permet à l'utilisateur d'ouvrir le lien dans l'application first party s'il le souhaite, en agissant en tant que proxy. Avant de configurer une telle boîte de dialogue ou activité trampoline, configurez votre application pour qu'elle ait une visibilité des packages dans les applications propriétaires qui correspondent au filtre d'intent Web de votre application.