SHA-256 d’assetlinks.json après Play App Signing: supprimer la barre de navigateur de la TWA

Ce guide traite d’une seule réparation: l’association entre votre site et la version que Google Play distribue. Il ne couvre ni la création de la TWA elle-même ni l’examen de l’application par Play, qui ont leurs propres guides, en lien ci-dessous. Chaque page Google citée ici a été vérifiée le 16 octobre 2026, et les sources figurent à la fin.

Pourquoi la barre de navigateur n’apparaît que sur l’installation Play

Chrome vérifie une TWA en comparant le certificat qui a signé l’application installée avec les empreintes publiées par votre site. Quand cette vérification échoue, le guide de démarrage rapide TWA de Chrome indique que le navigateur se rabat sur l’affichage de votre site dans un onglet personnalisé (Custom Tab). C’est ce repli qui produit la barre d’adresse que vous voyez.

Avec Play App Signing, il y a généralement deux certificats. Vous signez le bundle que vous importez avec votre clé d’importation, et Google signe les APK qu’il distribue avec la clé de signature d’application. La page Android concepts for web developers de Chrome indique que l’empreinte de la clé de signature d’application est celle qui correspond à votre application lorsqu’elle est téléchargée depuis le Play Store. Un fichier qui ne mentionne que votre certificat local passe donc sur votre bureau et échoue sur chaque téléphone qui a installé l’application depuis Play.

Les deux clés ne sont pas toujours différentes. La documentation Android sur la signature d’application décrit des configurations où la même clé sert à la fois de clé de signature d’application et de clé d’importation. La solution consiste donc à comparer les vrais certificats, pas à supposer lequel vous avez.

Trouver le SHA-256 de signature d’application dans la Play Console

La documentation de Google donne actuellement deux libellés pour le même emplacement. Les deux partent de Protected with Play dans le menu de gauche de votre application.

Des guides plus anciens, y compris certaines pages Google, indiquent encore Release > Setup > App signing ou Setup > App integrity. Si vous ne trouvez que ces libellés, c’est la même page sous un ancien nom.

Lire l’empreinte d’une clé que vous détenez vous-même

Pour votre clé d’importation ou une clé de debug, l’outil keytool de Java affiche le même format. Remplacez le fichier keystore et l’alias par les vôtres, puis copiez la ligne intitulée SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Si vous gérez de nombreuses applications, l’API Google Play Developer peut aussi renvoyer le hachage du certificat des APK générés par Play (le champ certificateSha256Hash de la liste des APK générés). Pour une correction ponctuelle, copier depuis la Play Console est plus simple.

Rédiger et servir un fichier assetlinks.json correct

Le fichier est un tableau JSON de déclarations. Pour une TWA, la relation est delegate_permission/common.handle_all_urls, et la cible est votre application Android: l’espace de noms android_app, votre ID d’application exact et un tableau d’empreintes SHA-256. Un fichier minimal ressemble à ceci:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Remplacez com.example.twa par votre ID d’application et chaque espace réservé par un SHA-256 complet, séparé par des deux-points. Supprimez la deuxième entrée si vous voulez seulement que les installations Play soient vérifiées. Du JSON strict uniquement: pas de commentaires, pas de virgules finales, pas de valeurs SHA-1.

Comment Google exige que le fichier soit servi

• Emplacement exact. https://your-domain/.well-known/assetlinks.json, avec le point dans .well-known. example.com et www.example.com sont des origines différentes; publiez le fichier sur chacune de celles que votre application ouvre. Une copie dans un sous-répertoire comme /app/.well-known/ ne compte pas.
• Un HTTP 200 direct. La documentation Digital Asset Links de Google indique: “Any response from the server besides HTTP 200 is treated as an error, and will result in an empty statement list.” (toute réponse du serveur autre que HTTP 200 est traitée comme une erreur et produit une liste de déclarations vide)
• Aucune redirection. Les réponses 301 et 302 ne sont pas suivies. Cela inclut un passage de http à https et un passage du domaine nu vers www.
• HTTPS avec une chaîne de certificats valide, et l’en-tête Content-Type: application/json. Une page de connexion ou une page d’erreur HTML qui répond 200 n’est pas un fichier valide.

Vérifiez la réponse en ligne depuis n’importe quel terminal. La première ligne d’état doit être 200 et le type de contenu doit être JSON, sans aucun 3xx avant:

curl -sI https://example.com/.well-known/assetlinks.json

Plusieurs empreintes, plusieurs applications

Le guide Android sur l’association de sites web dit du tableau d’empreintes: “This field supports multiple fingerprints, which can be used to support different versions of your app, such as debug and production builds.” (ce champ accepte plusieurs empreintes, pour prendre en charge différentes versions de votre application, par exemple debug et production). N’ajoutez une empreinte d’importation ou de debug que pour les versions auxquelles vous voulez vraiment que ce site fasse confiance. Une version avec un ID d’application différent, comme un package de debug distinct, nécessite sa propre déclaration dans le tableau.

Si vous avez créé la TWA avec Bubblewrap ou PWABuilder

Dans un projet Bubblewrap existant, ajoutez l’empreinte de Play et régénérez le fichier:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Générer le fichier ne revient pas à le déployer: importez le nouveau assetlinks.json sur votre site et vérifiez-le avec curl. bubblewrap validate évalue votre PWA selon des critères de qualité; il ne vérifie pas l’association de signature, donc une réussite à ce test ne prouve rien sur l’empreinte. Les instructions actuelles de PWABuilder font la même remarque sur la signature, “Once you've uploaded your .aab file, Google Play re-signs your app” (une fois votre fichier .aab importé, Google Play signe à nouveau votre application), et vous demandent d’ajouter l’empreinte de Play au fichier généré. Corriger une empreinte, c’est modifier votre site, pas le binaire de l’application.

Vérifier l’association, puis tester l’installation Play

Quatre couches entrent en jeu: le fichier sur votre site, l’API Digital Asset Links de Google, la vérification des liens propre à Android et le navigateur qui lance votre TWA. Réussir une couche ne prouve pas que la suivante passera: vérifiez-les dans l’ordre et terminez sur l’appareil.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

L’App Links Assistant d’Android Studio (Tools > App Links Assistant) vérifie l’association Android App Links et votre manifeste. Il est utile pour cela, mais il ne vous dit pas si votre TWA s’ouvre en plein écran; seul le test sur l’appareil le fait.

Avancé: l’état de vérification propre à Android

Sur Android 12 et versions ultérieures, le guide de vérification d’Android documente ces commandes pour les App Links. Remplacez le package, exécutez les deux premières, attendez quelques minutes, puis lisez l’état:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified décrit la validation de domaine d’Android, pas le fait que votre TWA s’ouvre sans l’interface du navigateur. Les codes de 1024 ou plus sont des erreurs propres au vérificateur, pas le diagnostic d’un SHA-256 erroné. Pour la TWA elle-même, utilisez le journal Chrome ci-dessus.

L’empreinte correspond mais la barre reste

Une barre visible ne prouve pas que le SHA-256 est faux. Quand la vérification ci-dessus renvoie linked: true et que la barre est toujours là, passez en revue ces causes.

Combien de temps avant qu’un fichier corrigé prenne effet

Google ne publie aucun délai unique pour les TWA, car plusieurs caches interviennent et chacun a ses propres règles:

• Votre serveur ou votre CDN peut encore servir l’ancien fichier. Videz le cache et confirmez la réponse en ligne avec curl.
• L’API Digital Asset Links indique dans son champ maxAge combien de temps chaque réponse reste valide.
• Android App Links a son propre calendrier. Le guide de vérification d’Android indique que sur Android 15 et versions ultérieures, les modifications peuvent mettre jusqu’à sept jours pour atteindre tous les appareils, et que sur Android 14 et versions antérieures le fichier est généralement pris en compte lors de l’installation ou de la mise à jour de l’application.
• Le navigateur peut conserver son propre état. Un développeur a signalé un succès après avoir effacé les données de Chrome.

Videz donc le cache, confirmez le fichier en ligne et réinstallez depuis Google Play. Sur un appareil de test, une nouvelle installation ou l’effacement des données du navigateur permet d’écarter un état en cache; c’est une étape de diagnostic, pas une démarche à demander à chaque utilisateur. Ne comptez pas sur un nombre d’heures fixe.

Refus, examen et test fermé

Un fichier assetlinks.json absent ou erroné n’est pas documenté comme une cause de refus à lui seul. Ce que la documentation décrit, c’est le repli vers un Custom Tab avec l’interface du navigateur. L’examen est une autre question: le règlement sur les fonctionnalités de Google Play indique “We don’t allow apps that crash, force close, freeze, or otherwise function abnormally,” (les applications qui plantent, se ferment de force, se figent ou fonctionnent anormalement de toute autre manière ne sont pas autorisées) et cela s’applique quel que soit l’état de votre association. Une empreinte correcte supprime la barre; elle ne règle pas l’examen. Si vous avez reçu un refus, partez du règlement cité dans l’e-mail.

Certains articles plus anciens affirment que Chrome fait planter une TWA qui échoue à ses contrôles de qualité. Chromium a supprimé ce code QualityEnforcer le 4 mai 2023: considérez donc ce conseil comme historique, et non comme une description des navigateurs actuels.

Si vous avez reçu un refus, partez du motif indiqué dans la notification: le refus Broken Functionality détaille la notification de fonctionnalité la plus courante. Ne reconstruisez pas votre TWA en WebView uniquement à cause d’une barre de navigateur. Si votre application sort d’un outil de création par IA, publier une application vibe-codée sur Google Play couvre tout le parcours, du projet jusqu’à Play.

Questions fréquentes

L’essentiel

Les libellés des menus de la Play Console sont l’information qui change le plus vite sur cette page. Si les chemins ci-dessus ne correspondent plus à votre Console, cherchez Play app signing sous Protected with Play, ou recherchez "app signing" dans la Console.