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 équipé d'Android 6.0 (niveau d'API 23) ou version ultérieure entraîne la validation 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 le processus 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.

Une fois que vous avez confirmé la liste des sites Web à associer à votre application et que vous avez confirmé que le fichier JSON hébergé est valide, installez l'application sur votre appareil. Patientez au moins 20 secondes pour que le processus 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 Android 12 ou non.

Établir une connexion Internet

Pour effectuer la validation de domaine, votre appareil de test doit être connecté à Internet.

Prendre en charge le processus de validation de domaine mis à jour

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

Sinon, vous pouvez activer manuellement le processus de validation mis à 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 de 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.

Appeler le processus de validation de domaine

Une fois que vous avez réinitialisé l'état des liens vers l'application Android sur un appareil, vous pouvez effectuer la validation 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

Examiner les résultats de la validation

Après avoir laissé un peu de temps à l'agent de validation pour 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

La sortie de cette commande est semblable à la suivante :

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 réussissent la validation ont un état de validation de domaine verified. Tout autre état indique que la validation de 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 présente 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 de domaine, puis appelez à nouveau le processus de validation de domaine.
verified
Le domaine est validé pour l'application déclarante.
approved
Le domaine a été approuvé de force, généralement en exécutant une commande shell.
denied
Le 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 la validation de domaine héritée.
restored
Le domaine a été approuvé après que l'utilisateur a effectué une restauration des données. Il est supposé que le domaine a été validé précédemment.
legacy_failure
Le domaine a été rejeté par un validateur hérité. 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 validateur de l'appareil.

Vérifiez que vous avez établi une connexion réseau, puis appelez à nouveau le processus de validation de 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.

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 <intent-filter> éléments. Vous pouvez interroger l'état d'approbation à l'aide de l'une des méthodes suivantes :

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 de 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 sortie suivant, même si la validation de l'application a échoué pour le domaine "example.org", 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 dans lequel l'utilisateur sélectionne l'application associée à un domaine donné. Une explication complète de ces commandes est disponible dans la sortie de adb shell pm.

Fournir le contexte de la demande

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

Envoyer la demande

Une fois que l'utilisateur a compris ce que votre application lui demande de faire, envoyez 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.pkgpour 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'intent est appelé, les utilisateurs voient un écran de paramètres appelé Ouvrir par défaut. Cet écran contient un bouton radio appelé 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 une section appelée Liens à ouvrir dans cette application. Les utilisateurs peuvent alors sélectionner les domaines qu'ils souhaitent associer à votre application. Ils peuvent également sélectionner Ajouter un lien pour ajouter des domaines, comme illustré à la figure 2. Lorsque les utilisateurs sélectionnent ultérieurement un lien dans les domaines qu'ils ajoutent, le lien s'ouvre automatiquement dans votre application.

Lorsque la case d&#39;option est activée, une section en bas de l&#39;écran inclut des cases à cocher ainsi qu&#39;un bouton &quot;Ajouter un lien&quot;.
Figure 1. Écran des paramètres système où les utilisateurs peuvent choisir les liens qui s'ouvrent par défaut dans votre application.
Chaque case à cocher représente un domaine que vous pouvez ajouter. Les boutons de la boîte de dialogue sont &quot;Annuler&quot; et &quot;Ajouter&quot;.
Figure 2. Boîte de dialogue dans laquelle les utilisateurs peuvent choisir des domaines supplémentaires à associer à votre application.

Ouvrir dans votre application des domaines que votre application ne peut pas valider

La fonction principale de votre application peut être d'ouvrir des liens en tant que tiers, sans pouvoir valider les domaines qu'elle gère. Dans ce 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 propriétaire s'il le souhaite, en agissant comme un proxy. Avant de configurer une telle boîte de dialogue ou activité de trampoline, configurez votre application de sorte qu'elle ait une visibilité de package dans les applications propriétaires qui correspondent au filtre d'intent Web de votre application.

Latence de mise à jour de Digital Asset Links

Lorsque vous mettez à jour le fichier assetlinks.json sur votre serveur Web, le temps nécessaire pour que ces modifications soient reflétées sur les appareils des utilisateurs finaux dépend de la version de l'OS :

  • Android 15 (niveau d'API 35) et versions ultérieures : le système revalide périodiquement les domaines en arrière-plan. Un délai maximal de sept jours peut être nécessaire pour que les modifications soient appliquées à tous les appareils des utilisateurs finaux en raison de la mise en cache et de la revalidation planifiée du système.
  • Android 14 (niveau d'API 34) et versions antérieures : le système n'effectue pas de revalidation périodique en arrière-plan. Les mises à jour du fichier ne sont généralement récupérées que lorsque l'application est installée ou mise à jour.

Tester les mises à jour

Pour forcer une revalidation sur un appareil spécifique pendant les tests, vous pouvez désinstaller et réinstaller l'application. Toutefois, sachez que les caches côté serveur peuvent toujours retarder la diffusion du fichier assetlinks.json mis à jour sur l'appareil, même après la réinstallation. Comme le cache est basé sur le temps, le délai se résout généralement automatiquement si vous réessayez après quelques heures.