KappS Base de connaissances · Blog

Android App Links en 2026 : un tutoriel de vérification pas à pas

Blog Tutoriel

Un Android App Link est le seul mécanisme de lien profond que Google considère comme une preuve de propriété : votre application déclare un hôte HTTPS qu’elle accepte de gérer, publie une déclaration Digital Asset Links sur cet hôte, et Android vérifie que les deux correspondent avant d’ouvrir votre application à la place du navigateur. Deux artefacts décident du résultat — un fichier /.well-known/assetlinks.json que vous contrôlez et l’empreinte de signature SHA-256 qu’il contient — et la plupart des échecs viennent d’une légère erreur sur l’un des deux plutôt que d’un cas exotique.

Ce tutoriel suit l’ordre dans lequel le travail se déroule réellement : déclarer le filtre d’intention autoVerify, publier la liste de déclarations assetlinks.json, choisir la bonne empreinte lorsque Play App Signing re-signe votre build, installer et lire l’état de vérification, diagnostiquer les échecs courants en production, concevoir une solution de repli qui ne ment pas aux utilisateurs, et maintenir la vérification des liens d’application à travers les rotations de clés et les changements de domaine. La règle sous-jacente : la vérification est la promesse que le domaine et l’application ont le même propriétaire, donc la seule façon légitime de la réussir est de posséder réellement les deux.


1. Ce qu’un lien vérifié prouve, et ce qu’il ne prouve pas

Trois idées sont confondues, et les distinguer évite la plupart des mauvaises décisions de conception.

  • Un lien profond est toute intention qui ouvre un écran dans votre application. Il peut provenir d’un schéma personnalisé comme myapp://product/42, que toute application de l’appareil est autorisée à enregistrer, si bien qu’une application malveillante peut revendiquer le même schéma et recevoir l’URL à votre place.
  • An App Link is an HTTPS URL — https://shop.example.com/product/42 — that Android has verified you are entitled to handle, because that host publishes a statement naming your package and your signing certificate. The user sees a normal web URL, the browser can always open it, and only one app can win the verification.
  • Une solution de repli web, c’est la même URL ouverte dans un navigateur lorsque votre application n’est pas installée. Une stratégie de liens bien conçue fait dialoguer les trois briques : l’URL mène au contenu voulu, que l’application soit présente ou non.

Ce que la vérification ne fait pas : elle ne prouve pas que l’application est installée, elle ne vous accorde aucun droit sur le contenu du domaine et elle ne remplace pas l’authentification. Si un écran affiche des données de compte, c’est toujours la vérification du token côté serveur qui les protège. La vérification répond seulement à « cette application peut-elle ouvrir des liens pour cet hôte » — rien de plus.

Une conséquence pratique : réservez les schémas personnalisés au maximum aux échanges internes, et ne comptez jamais sur eux pour les réinitialisations de mot de passe ou les redirections de paiement, car la propriété d’un schéma n’est pas opposable.

2. Étape 1 — déclarer les filtres d'intent autoVerify dans le manifeste

Commencez dans AndroidManifest.xml. Le filtre doit être un filtre https avec android:autoVerify="true", et il nécessite l’action VIEW ainsi que les deux catégories DEFAULT et BROWSABLE :

<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" android:host="shop.example.com" /> </intent-filter>

Les détails qui déterminent si cela fonctionne en pratique :

  • Un filtre par hôte. La vérification est évaluée par hôte, et les recommandations de Google préconisent un <intent-filter> distinct par domaine. Regrouper cinq hôtes dans un seul filtre fait qu’un seul hôte défaillant contamine les autres.
  • Les hôtes sont littéraux. android:host n’accepte pas les caractères génériques. Atteignez les sous-domaines avec des filtres distincts et restreignez la portée avec android:path, android:pathPrefix ou android:pathPattern pour que l’application ne revendique pas des URL qu’elle ne peut pas afficher.
  • http n’est pas vérifiable. Seul https participe à la vérification automatique. Conserver un filtre http ne fait que créer des invites de sélection en double.
  • Ne déclarez que ce que vous traitez. Un filtre qui correspond à tout l'hôte alors que l'application gère trois chemins envoie toutes les autres URL vers un écran vide — et ce comportement apparaît dans les avis du store bien avant d'apparaître dans votre tableau de bord des plantages.

Si votre application gère à la fois un domaine marketing et un domaine applicatif, décidez délibérément lequel est canonique pour le partage. Chaque hôte que vous ajoutez est un fichier à publier et un certificat à maintenir synchronisé.

3. Étape 2 — publier /.well-known/assetlinks.json

La liste des relevés se trouve à un seul chemin, en HTTPS, sans redirection devant :

https://shop.example.com/.well-known/assetlinks.json

Le corps est un tableau JSON de déclarations. Pour une application ordinaire qui gère toutes les URL de l’hôte, une seule déclaration suffit :

[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.shop", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] } }]

Plusieurs packages, ou un seul package avec plusieurs certificats, ajoutent simplement davantage de déclarations au même tableau. Les spécificités de diffusion comptent autant que le contenu :

  • Type de contenu. Servez-le en application/json. Certaines versions de Android et certaines configurations de CDN en périphérie sont strictes sur ce point.
  • Aucune redirection. Une 301 ou 302 devant le fichier fait échouer la récupération, et l’échec est silencieux sur l’appareil. C’est l’erreur d’hébergement la plus courante — une règle globale « forcer HTTPS » ou « supprimer la barre oblique finale » la casse sans bruit.
  • Aucune authentification, aucun mur anti-bot. Le vérificateur de Google récupère le fichier de manière anonyme. Un défi WAF ou un blocage géographique renvoie une page d’erreur HTML là où du JSON est attendu.
  • JSON valide, sans commentaires. Une virgule finale ou un commentaire // égaré invalide tout le fichier, et chaque déclaration qu’il contient.

Before you debug anything on the device, fetch the file the way the verifier would: curl -sI https://shop.example.com/.well-known/assetlinks.json should show 200 and no Location header, and the body should parse. Google publishes a statement list generator and tester that will validate the structure and the fingerprint format for you — use it before shipping.

4. Étape 3 — utiliser l’empreinte que l’appareil voit réellement

C'est ici que la plupart des vérifications échouent, et la raison est Play App Signing. À l'inscription, Google détient la clé de signature de l'application et re-signe chaque artefact qu'il livre. Le certificat installé sur l'appareil d'un utilisateur est donc le certificat de signature de l'application — et non la clé de téléversement que vous avez sur votre machine de build.

  • Les installations Play nécessitent le certificat SHA-256 de la clé de signature de l’application, disponible dans la Play Console sous Intégrité de l’application → Signature de l’application (bloc « Certificat de clé de signature de l’application »).
  • Les builds locaux et installés en sideload sont signés avec votre clé d’upload ou de débogage et nécessitent cette empreinte — lisez-la avec keytool -list -v -keystore <keystore> et copiez la ligne SHA-256.
  • Publiez les deux. Déclarer le certificat de signature de l’application et le certificat d’upload dans le même tableau sha256_cert_fingerprints est normal et attendu : les installations Play peuvent ainsi être vérifiées pendant que vos builds QA continuent de fonctionner.

Deux autres pièges dans le même domaine. Si vous utilisez un keystore de débogage, son empreinte est propre à la machine qui l'a généré — parfait pour vos propres tests, inutile dans le fichier publié. Et si vous utilisez un jour la mise à niveau de clé de Play, le certificat change : la liste d'énoncés doit être mise à jour avant le déploiement de la mise à niveau, sinon les liens se cassent pour les nouvelles installations tandis que les anciennes continuent de fonctionner.

Copiez les empreintes depuis la console plutôt que de les ressaisir. Une seule paire de chiffres hexadécimaux inversés produit un fichier JSON valide, servi avec un code 200, qui échoue malgré tout à la vérification sans le moindre message d’erreur.

5. Étape 4 — installer et lire l’état de vérification réel

La vérification est tentée à l’installation de l’application, puis de nouveau après les mises à jour : vous devez donc installer l’application depuis le canal que vous testez — une installation via le test interne Play se comporte différemment d’un adb install d’une build signée pour le téléversement.

Sur Android 12 et versions supérieures, interrogez directement la plateforme :

adb shell pm get-app-links com.example.shop

Vous recevez un rapport par domaine : le domaine, si l’utilisateur l’a approuvé et l’état de vérification — verified lorsque la liste de déclarations correspond, denied ou legacy_failure dans le cas contraire. Sur les anciennes versions, l’équivalent est un export des enregistrements de vérification de domaine :

adb shell dumpsys package d

Si un hôte apparaît comme refusé et que vous venez de corriger le fichier, forcez une nouvelle tentative au lieu de réinstaller à l’aveugle :

adb shell pm set-app-links --package com.example.shop --domain shop.example.com all

Testez ensuite le parcours qu’effectue un utilisateur. Un lien saisi dans un navigateur, un lien touché dans un client de messagerie et un lien à l’intérieur d’une autre application ne se résolvent pas toujours de la même façon, et un seul d’entre eux peut passer par le sélecteur. Vérifiez aussi l’écran Ouvrir par défaut de l’application dans les réglages système : un utilisateur peut désactiver un lien vérifié, et votre code doit y survivre sans se briser.

6. Étape 5 — diagnostiquer les échecs que vous rencontrerez réellement

Presque toutes les défaillances en production entrent dans l’une des cinq catégories. Vérifiez-les dans cet ordre ; chacune prend quelques secondes.

  1. Empreinte incorrecte. Le fichier s’analyse, l’hôte est correct, et le certificat mentionné dans la déclaration est la clé d’upload alors que l’appareil exécute la version signée par Play. Comparez l’empreinte du console caractère par caractère avec celle du fichier.
  2. Redirection ou type de contenu incorrect. curl -sI affiche un 3xx, un text/html ou une page d’erreur mise en cache par le CDN. Corrigez l’en-tête, purgez le cache, puis vérifiez à nouveau.
  3. Incohérence entre le nom de package et l’hôte. Un identifiant d’application modifié pour un build en marque blanche, ou un filtre qui liste encore un hôte de staging qui ne sert plus le fichier. Passez le manifeste au crible pour chaque hôte et confirmez que chacun dispose d’une déclaration active.
  4. La vérification n’a jamais eu lieu. L’installation s’est faite hors ligne, ou l’application n’a jamais été lancée depuis l’installation. Ouvrez l’application une fois avec une connexion, puis relancez pm get-app-links.
  5. Priorité utilisateur. Le domaine a été désactivé dans les paramètres — parfois des mois plus tôt, parfois par un outil de migration d’un fabricant. pm set-app-links … all le réinitialise pour les tests ; pour les vrais utilisateurs, la solution est la pédagogie, pas la contrainte.

Gardez un test de fumée d’une ligne dans votre liste de vérification de version : récupérez le fichier, analysez-le et vérifiez que l’empreinte correspond à celle affichée actuellement par la console. Un changement de domaine ou une mise à niveau de clé qui saute ce contrôle est exactement la façon dont une configuration de lien fonctionnelle meurt en silence.

7. Étape 6 — mettre en place une solution de repli qui dit la vérité

Les App Links font de l'application le gestionnaire préféré ; ils n'en font pas le seul. Concevez d'abord le côté web, car c'est le cas qui existe toujours.

  • L’URL doit s’afficher sans l’application. Un lien de partage qui ne fonctionne qu’une fois l’application installée est un lien cassé, et il bloque aussi les robots d’indexation.
  • Détectez, puis proposez — ne détournez pas. Une petite bannière avec « Ouvrir dans l’application » et un lien vers le store convertit mieux qu’une redirection automatique qui piège les utilisateurs voulant délibérément rester dans le navigateur.
  • Gardez le chemin de deep link identique au chemin web. Si l’application affiche /product/42, la page web au même chemin doit afficher le même produit ; la table de correspondance que vous évitez de construire est celle qui cassera au prochain trimestre.
  • Gérez le cas de l’installation en attente. Le deep linking différé — où un nouvel utilisateur installe l’application et atterrit sur l’élément partagé — nécessite un mécanisme côté serveur ou basé sur le referrer d’installation. Firebase Dynamic Links, l’outil utilisé par la plupart des équipes, a été retiré : prévoyez donc l’Install Referrer API ou un équivalent maison plutôt que de compter sur un service hébergé.

Et résistez à la tentation de rendre la vérification invisible. Si l’application ne peut pas afficher une URL, laisser le navigateur s’en charger est une meilleure issue qu’un écran « introuvable » côté application, et cela préserve le référencement du domaine.

8. Maintenir la vérification active au fil des versions et des domaines

La vérification n’est pas une configuration ponctuelle. C’est un accord permanent entre trois éléments mouvants : le manifeste, le fichier publié et le certificat avec lequel le store signe réellement. Tout ce qui touche à l’un d’eux est un point de la liste de vérification avant soumission.

  • Mise à niveau ou nouvelle signature de clé. Mettez à jour assetlinks.json avec le nouveau certificat et publiez-le avant le déploiement, puis conservez l’ancien jusqu’au retrait complet de la version précédente.
  • Changement de domaine. Publiez d'abord les fichiers de déclaration sur le nouvel hôte, déployez ensuite la modification du manifeste. Un filtre pointant vers un hôte sans fichier met immédiatement les liens hors ligne.
  • Domaines de marque et régionaux. Chaque hôte est une déclaration et un fichier à part. Automatisez le déploiement pour qu’un nouveau domaine régional ne puisse pas être mis en ligne sans le sien.
  • Vérifications de propriété. Le fichier est une déclaration publique que vous contrôlez le domaine. Ne le publiez que pour des domaines que votre organisation possède et exploite, et n’hébergez jamais la déclaration d’un tiers à sa place — c’est exactement le schéma que recherche la détection d’abus, et cela met en danger à la fois le domaine et le compte de l’application.

Conservez les filtres du manifeste, le modèle JSON publié et les empreintes actuelles au même endroit, générés à partir d’une source unique de vérité. Lorsqu’il s’agit de trois modifications manuelles distinctes, ils divergent en deux cycles de publication.

9. Où se situe KappS

Nous intervenons sur le versant opérationnel de la publication : maintenir les comptes, les versions et les enregistrements de store dans un état qui résiste à l’examen des plateformes — préparer et soumettre des éléments conformes, jamais contourner un contrôle. Pour la vérification des liens, cela signifie généralement :

  • Hygiène de publication. Certificats et identifiants d'application cohérents entre la console, le build et la liste d'instructions publiée, pour que l'empreinte vue par l'appareil soit celle que vous avez documentée.
  • Préparation du compte. Vérification du développeur, profil de paiement et informations fiscales alignés sur l’entité juridique derrière le compte, pour qu’une mise en ligne ne soit pas bloquée par un examen sans rapport.
  • Vérification du domaine et de l’hébergement. S’assurer que le chemin well-known sert bien du JSON, sans redirection, sans challenge WAF et sans page d’erreur en cache devant lui.

Ce que nous ne faisons pas : publier des déclarations pour des domaines qu’un client ne possède pas, usurper une empreinte, ou aider une application à revendiquer un hôte auquel elle n’a pas droit. La vérification existe précisément pour protéger les utilisateurs de cela, et ce n’est pas un service que nous proposons.

Sources (documentation officielle) : Android Developers — Verify Android App Links ; Add Android App Links ; spécification Digital Asset Links ; Play Console Help — App signing key certificate and key upgrade ; Android Developers — commandes Adb shell pm pour les liens d'application.

Vous gérez des comptes développeur à grande échelle ? Nous prenons en charge le volet opérationnel.

Cliquez pour choisir un fichier · clic droit → Coller, ou appuyez sur Ctrl/⌘+V pour coller une capture d’écran

Vous pouvez aussi glisser un fichier sur cette zone.

Nous répondons à l’e-mail que vous indiquez. Vos données restent chez KappS.

✔ Soumis

Nous avons bien reçu votre message et vous répondrons sous 24 heures.


← Retour à la modification