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 ou version ultérieure, 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 :
- Le système inspecte tous les filtres d'intentions qui incluent l'un des éléments suivants :
- Action :
android.intent.action.VIEW - Catégories :
android.intent.category.BROWSABLEetandroid.intent.category.DEFAULT - Schéma de données :
httpouhttps
- Action :
- Pour chaque nom d'hôte unique trouvé dans les filtres d'intent, Android interroge les sites Web correspondants pour obtenir le fichier Digital Asset Links à l'adresse https://hostname/.well-known/assetlinks.json.
Après avoir confirmé la liste des sites Web à associer à votre application et vérifié que le fichier JSON hébergé est valide, installez l'application sur votre appareil. Patientez au moins 20 secondes, le temps 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 du domaine, votre appareil de test doit être connecté à Internet.
Prise en charge de la nouvelle procédure de validation du domaine
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 la nouvelle procédure de validation. 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 une application Android sur un appareil
Avant d'appeler manuellement la validation de domaine sur un appareil, vous devez réinitialiser l'état des liens d'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 l'état où il se trouvait avant que l'utilisateur ne choisisse des applications par défaut pour les domaines.
Appeler le processus de validation du domaine
Après avoir réinitialisé l'état des liens vers l'application Android sur un appareil, vous pouvez effectuer la validation proprement dite. 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 la 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 ont été validés ont l'état de validation de domaine verified. Tout autre état indique que la validation du domaine n'a pas pu être effectuée. En particulier, l'é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. Attendez quelques minutes que l'agent de validation termine les requêtes liées à la validation du domaine, puis appelez à nouveau la procédure de validation du domaine.
verified- Le domaine a bien été validé pour l'application de déclaration.
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 l'ancienne validation de domaine.
restored- Le domaine a été approuvé après que l'utilisateur a restauré les données. Nous partons du principe que le domaine a déjà été validé.
legacy_failure- Le domaine a été refusé par un ancien validateur. 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 supérieur ou égal à
1024 Code d'erreur personnalisé spécifique au vérificateur de l'appareil.
Vérifiez que vous avez établi une connexion réseau, puis lancez à nouveau la procédure de validation du domaine.
Demander à l'utilisateur d'associer votre application à un domaine
Pour que votre application soit approuvée pour un domaine, vous pouvez également 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 é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 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 résultat 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 par lequel l'utilisateur sélectionne l'application associée à un domaine donné. Une explication complète de ces commandes est disponible dans le résultat de adb shell pm.
Fournir du contexte pour la requête
Avant d'envoyer cette demande d'approbation de domaine, fournissez un peu de 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 requête
Une fois que l'utilisateur a compris ce que votre application lui demande de faire, envoyez la requête.
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'intent est appelé, les utilisateurs voient un écran de paramètres intitulé Ouvrir par défaut. Cet écran contient une case d'option appelée Ouvrir les liens compatibles, comme illustré dans 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é dans la figure 2. Lorsque les utilisateurs sélectionnent un lien dans les domaines qu'ils ajoutent, le lien s'ouvre automatiquement dans votre application.
Ouvrir dans votre application des domaines qu'elle 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. Si c'est le cas, expliquez aux utilisateurs qu'à ce moment-là, 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é trampoline, configurez votre application de sorte qu'elle dispose d'une visibilité des packages 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 prises en compte sur les appareils des utilisateurs finaux dépend de la version de l'OS :
- Android 15 (niveau d'API 35) ou version ultérieure : le système revérifie régulièrement les domaines en arrière-plan. La propagation des modifications sur tous les appareils des utilisateurs finaux peut prendre jusqu'à sept jours en raison de la mise en cache du système et de la revérification planifiée.
- Android 14 (niveau d'API 34) ou version antérieure : le système n'effectue pas de nouvelle validation périodique en arrière-plan. Les mises à jour du fichier ne sont généralement prises en compte que lorsque l'application est installée ou mise à jour.
Tester les mises à jour
Pour forcer une nouvelle validation 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. Étant donné que 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.