assetlinks.json SHA-256 na Play App Signing: zo verdwijnt de browserbalk in je TWA

Deze gids behandelt één reparatie: de koppeling tussen je website en de build die Google Play levert. Het bouwen van de TWA zelf en de beoordeling van de app door Play vallen erbuiten; daarvoor zijn aparte gidsen, hieronder gelinkt. Elke Google-pagina die we hier aanhalen is gecontroleerd op 16 oktober 2026, en de bronnen staan onderaan.

Waarom de browserbalk alleen bij de installatie via Play verschijnt

Chrome verifieert een TWA door het certificaat waarmee de geïnstalleerde app is ondertekend te vergelijken met de vingerafdrukken die je website publiceert. Mislukt die controle, dan valt de browser volgens de TWA quick start van Chrome terug op het tonen van je site als Custom Tab. Die terugval is de adresbalk die je ziet.

Met Play App Signing zijn er meestal twee certificaten. Je ondertekent de bundle die je uploadt met je uploadsleutel, en Google ondertekent de APK's die het levert met de app-ondertekeningssleutel. Volgens de pagina Android concepts for web developers van Chrome is de vingerafdruk van de app-ondertekeningssleutel degene die bij je app hoort wanneer die uit de Play Store wordt gedownload. Een bestand dat alleen je lokale certificaat vermeldt, slaagt dus op je eigen bureau en faalt op elke telefoon die de app via Play heeft geïnstalleerd.

De twee sleutels zijn niet altijd verschillend. De documentatie over app-ondertekening van Android beschrijft configuraties waarin dezelfde sleutel zowel als app-ondertekeningssleutel als uploadsleutel dient. De oplossing is dus de echte certificaten te vergelijken, niet aan te nemen welke je hebt.

De SHA-256 van de app-ondertekening vinden in Play Console

De eigen documentatie van Google geeft momenteel twee labels voor dezelfde plek. Beide beginnen bij Protected with Play in het menu links van je app.

Oudere gidsen, waaronder sommige Google-pagina's, noemen nog Release > Setup > App signing of Setup > App integrity. Vind je alleen die labels, dan zoek je dezelfde pagina onder een oudere naam.

De vingerafdruk lezen van een sleutel die je zelf beheert

Voor je uploadsleutel of een debugsleutel drukt keytool van Java hetzelfde formaat af. Vervang het keystore-bestand en de alias door die van jezelf en kopieer de regel met het label SHA256:

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

Beheer je veel apps, dan kan de Google Play Developer API ook de certificaathash teruggeven van de APK's die Play heeft gegenereerd (het veld certificateSha256Hash in de lijst met gegenereerde APK's). Voor één enkele reparatie is kopiëren uit Play Console eenvoudiger.

Een correcte assetlinks.json schrijven en publiceren

Het bestand is een JSON-array met statements. Voor een TWA is de relatie delegate_permission/common.handle_all_urls, en het doel is je Android-app: de namespace android_app, je exacte applicatie-ID en een array met SHA-256-vingerafdrukken. Een minimaal bestand ziet er zo uit:

[
  {
    "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"
      ]
    }
  }
]

Vervang com.example.twa door je applicatie-ID en elke placeholder door een volledige SHA-256 met dubbele punten. Verwijder de tweede regel als alleen installaties via Play hoeven te worden geverifieerd. Alleen strikte JSON: geen commentaar, geen afsluitende komma's, geen SHA-1-waarden.

Hoe Google wil dat het bestand wordt aangeboden

• Exacte locatie. https://your-domain/.well-known/assetlinks.json, met de punt in .well-known. example.com en www.example.com zijn verschillende origins; publiceer het bestand op elke origin die je app opent. Een kopie in een submap zoals /app/.well-known/ telt niet.
• Een directe HTTP 200. De documentatie over Digital Asset Links van Google zegt: “Elk antwoord van de server anders dan HTTP 200 wordt als fout behandeld en levert een lege lijst met statements op.”
• Geen redirects. Antwoorden met 301 en 302 worden niet gevolgd. Dat geldt ook voor een sprong van http naar https en van het kale domein naar www.
• HTTPS met een geldige certificaatketen, en de header Content-Type: application/json. Een inlogpagina of een HTML-foutpagina die met 200 antwoordt, is geen geldig bestand.

Controleer het live antwoord vanuit een willekeurige terminal. De eerste statusregel moet 200 zijn en het contenttype moet JSON zijn, zonder 3xx ervoor:

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

Meer dan één vingerafdruk, meer dan één app

De gids over websitekoppelingen van Android zegt over de array met vingerafdrukken: “Dit veld ondersteunt meerdere vingerafdrukken, waarmee je verschillende versies van je app kunt ondersteunen, zoals debug- en productiebuilds.” Voeg een upload- of debugvingerafdruk alleen toe voor builds die die website echt moet vertrouwen. Een build met een andere applicatie-ID, zoals een apart debugpakket, heeft een eigen statement in de array nodig.

Als je de TWA met Bubblewrap of PWABuilder hebt gebouwd

Voeg in een bestaand Bubblewrap-project de vingerafdruk van Play toe en genereer het bestand opnieuw:

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

Het bestand genereren is niet hetzelfde als het publiceren: upload de nieuwe assetlinks.json naar je website en controleer hem met curl. bubblewrap validate toetst je PWA aan kwaliteitscriteria; het controleert de ondertekeningskoppeling niet, dus slagen daar bewijst niets over de vingerafdruk. De huidige instructies van PWABuilder maken hetzelfde punt over ondertekening, “Zodra je je .aab-bestand hebt geüpload, ondertekent Google Play je app opnieuw”, en vragen je de vingerafdruk van Play aan het gegenereerde bestand toe te voegen. Een correctie van de vingerafdruk is een wijziging aan je website, niet aan de app-binary.

Controleer de koppeling en test daarna de installatie via Play

Er spelen vier lagen mee: het bestand op je website, de Digital Asset Links API van Google, de eigen linkverificatie van Android en de browser die je TWA start. Slagen op de ene laag bewijst de volgende niet, dus controleer ze op volgorde en eindig op het apparaat.

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

De App Links Assistant van Android Studio (Tools > App Links Assistant) controleert de koppeling van Android App Links en je manifest. Daarvoor is hij nuttig, maar hij vertelt je niet of je TWA schermvullend opent; dat doet alleen de test op het apparaat.

Geavanceerd: de eigen verificatiestatus van Android

Op Android 12 en hoger documenteert de verificatiegids van Android deze commando's voor App Links. Vervang het pakket, voer de eerste twee uit, wacht een paar minuten en lees dan de status:

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 beschrijft de domeinverificatie van Android, niet of je TWA zonder browser-UI opent. Codes van 1024 of hoger zijn verifier-specifieke fouten, geen diagnose van een verkeerde SHA-256. Gebruik voor de TWA zelf het Chrome-log hierboven.

De vingerafdruk klopt, maar de balk blijft

Een zichtbare balk bewijst niet dat de SHA-256 fout is. Geeft de controle hierboven linked: true terug en staat de balk er nog, loop dan deze oorzaken na.

Hoe lang het duurt voordat een hersteld bestand werkt

Google publiceert geen vaste wachttijd voor TWA's, omdat er meerdere caches meespelen en elke cache eigen regels heeft:

• Je server of CDN kan nog het oude bestand aanbieden. Leeg de cache en bevestig het live antwoord met curl.
• De Digital Asset Links API geeft in het veld maxAge aan hoe lang elk antwoord geldig blijft.
• Android App Links heeft een eigen timing. De verificatiegids van Android zegt dat wijzigingen op Android 15 en hoger tot zeven dagen kunnen duren voordat ze alle apparaten bereiken, en dat het bestand op Android 14 en lager doorgaans wordt opgehaald wanneer de app wordt geïnstalleerd of bijgewerkt.
• De browser kan een eigen status bewaren. Eén ontwikkelaar meldde succes na het wissen van de gegevens van Chrome.

Leeg dus de cache, bevestig het live bestand en installeer de app opnieuw via Google Play. Op een testapparaat kun je met een nieuwe installatie of het wissen van de browsergegevens een gecachete status uitsluiten; dat is een diagnostische stap, niet iets wat je aan elke gebruiker vraagt. Plan niet rond een vast aantal uren.

Afwijzing, beoordeling en gesloten test

Een ontbrekende of verkeerde assetlinks.json is niet gedocumenteerd als zelfstandige oorzaak van een afwijzing. Wat de documentatie beschrijft, is de terugval op een Custom Tab met browser-UI. De beoordeling is een aparte kwestie: het functionaliteitsbeleid van Google Play zegt “We staan geen apps toe die crashen, geforceerd sluiten, vastlopen of op een andere manier abnormaal functioneren,” en dat geldt ongeacht de status van je koppeling. Een correcte vingerafdruk lost de balk op; de beoordeling is daarmee niet beslist. Heb je een afwijzing ontvangen, begin dan bij het beleid dat in de e-mail wordt genoemd.

Sommige oudere artikelen beweren dat Chrome een TWA laat crashen als die niet aan de kwaliteitscontroles voldoet. Chromium heeft die QualityEnforcer-code op 4 mei 2023 verwijderd, dus beschouw dat advies als historisch en niet als een beschrijving van de huidige browsers.

Heb je een afwijzing ontvangen, werk dan vanuit de reden in de melding: de afwijzing wegens Broken Functionality loopt de meest voorkomende melding over functionaliteit door. Bouw je TWA niet om tot een WebView alleen vanwege een browserbalk. Komt je app uit een AI-builder, dan beschrijft een vibe-coded app publiceren op Google Play de volledige route van project naar Play.

Veelgestelde vragen

Conclusie

De menulabels van Play Console zijn het snelst veranderende feit op deze pagina. Komen de routes hierboven niet meer overeen met je Console, zoek dan Play app signing onder Protected with Play, of zoek in de Console op app signing.