assetlinks.json SHA-256 After Play App Signing: Fix the TWA Browser Bar

This guide covers one repair: the association between your website and the build Google Play delivers. It does not cover building the TWA itself or Play's review of the app, which have their own guides linked below. Every Google page cited here was checked on October 16, 2026, and the sources are listed at the end.

Why the browser bar appears only on the Play install

Chrome verifies a TWA by comparing the certificate that signed the installed app with the fingerprints your website publishes. When that check fails, Chrome's TWA quick start says the browser falls back to showing your site as a Custom Tab. That fallback is the address bar you see.

With Play App Signing there are usually two certificates. You sign the bundle you upload with your upload key, and Google signs the APKs it delivers with the app signing key. Chrome's Android concepts for web developers page says the app signing key fingerprint is the one that corresponds to your app when it is downloaded from the Play Store. A file that lists only your local certificate therefore passes on your desk and fails on every phone that installed from Play.

The two keys are not always different. Android's app signing documentation describes setups where the same key serves as both the app signing key and the upload key. So the fix is to compare the real certificates, not to assume which one you have.

Find the app signing SHA-256 in Play Console

Google's own documentation currently gives two labels for the same place. Both start at Protected with Play in the left menu of your app.

Older guides, including some Google pages, still say Release > Setup > App signing or Setup > App integrity. If you only find those labels, you are looking for the same page under an older name.

Read the fingerprint of a key you hold yourself

For your upload key or a debug key, Java's keytool prints the same format. Replace the keystore file and alias with your own, then copy the line labeled SHA256:

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

If you manage many apps, the Google Play Developer API can also return the certificate hash of the APKs Play generated (the certificateSha256Hash field of the generated APKs list). For a single fix, copying from Play Console is simpler.

Write and serve a correct assetlinks.json

The file is a JSON array of statements. For a TWA the relation is delegate_permission/common.handle_all_urls, and the target is your Android app: the namespace android_app, your exact application ID and an array of SHA-256 fingerprints. A minimal file looks like this:

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

Replace com.example.twa with your application ID and each placeholder with a full colon separated SHA-256. Delete the second entry if you only need Play installs to verify. Strict JSON only: no comments, no trailing commas, no SHA-1 values.

How Google requires the file to be served

• Exact location. https://your-domain/.well-known/assetlinks.json, with the dot in .well-known. example.com and www.example.com are different origins; publish the file on each one your app opens. A copy in a subdirectory such as /app/.well-known/ does not count.
• A direct HTTP 200. Google's Digital Asset Links documentation says: “Any response from the server besides HTTP 200 is treated as an error, and will result in an empty statement list.”
• No redirects. 301 and 302 responses are not followed. That includes an http to https hop and a bare domain to www hop.
• HTTPS with a valid certificate chain, and the header Content-Type: application/json. A login page or an HTML error page that answers with 200 is not a valid file.

Check the live response from any terminal. The first status line must be 200 and the content type must be JSON, with no 3xx before it:

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

More than one fingerprint, more than one app

Android's website association guide says of the fingerprint array: “This field supports multiple fingerprints, which can be used to support different versions of your app, such as debug and production builds.” Add an upload or debug fingerprint only for builds you actually want that website to trust. A build with a different application ID, such as a separate debug package, needs its own statement in the array.

If you built the TWA with Bubblewrap or PWABuilder

In an existing Bubblewrap project, add Play's fingerprint and regenerate the file:

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

Generating the file is not deploying it: upload the new assetlinks.json to your website and check it with curl. bubblewrap validate checks your PWA against quality criteria; it does not check the signing association, so a pass there proves nothing about the fingerprint. PWABuilder's current instructions make the same point about signing, “Once you've uploaded your .aab file, Google Play re-signs your app”, and tell you to add Play's fingerprint to the generated file. A fingerprint correction is a change to your website, not to the app binary.

Verify the association, then test the Play install

Four layers are involved: the file on your website, Google's Digital Asset Links API, Android's own link verification and the browser that launches your TWA. Passing one layer does not prove the next, so check them in order and finish on the device.

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

Android Studio's App Links Assistant (Tools > App Links Assistant) checks Android App Links association and your manifest. It is useful for those, but it does not tell you whether your TWA opens full screen; only the device test does.

Advanced: Android's own verification state

On Android 12 and higher, Android's verification guide documents these commands for App Links. Replace the package, run the first two, wait a few minutes, then read the state:

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 describes Android's domain verification, not whether your TWA opens without browser UI. Codes of 1024 or higher are verifier specific errors, not a diagnosis of a wrong SHA-256. For the TWA itself, use the Chrome log above.

The fingerprint matches but the bar stays

A visible bar does not prove the SHA-256 is wrong. When the check above returns linked: true and the bar is still there, work through these causes.

How long until a fixed file takes effect

Google publishes no single wait time for TWAs, because several caches are involved and each has its own rules:

• Your server or CDN may still serve the old file. Purge it and confirm the live response with curl.
• The Digital Asset Links API states how long each response stays valid in its maxAge field.
• Android App Links has separate timing. Android's verification guide says that on Android 15 and higher changes can take up to seven days to reach all devices, and that on Android 14 and lower the file is typically picked up when the app is installed or updated.
• The browser may keep its own state. One developer reported success after clearing Chrome's data.

So purge the cache, confirm the live file and reinstall from Google Play. On a test device, a fresh install or clearing the browser's data can rule out cached state; that is a diagnostic step, not something to ask every user to do. Do not plan around a fixed number of hours.

Rejection, review and closed testing

A missing or wrong assetlinks.json is not documented as a cause of rejection on its own. What the documentation describes is the fallback to a Custom Tab with browser UI. Review is a separate question: Google Play's functionality policy says “We don’t allow apps that crash, force close, freeze, or otherwise function abnormally,” and that applies whatever your association status is. A correct fingerprint fixes the bar; it does not settle review. If you received a rejection, start from the policy named in the email.

Some older articles say Chrome will crash a TWA that fails its quality checks. Chromium removed that QualityEnforcer code on May 4, 2023, so treat that advice as historical rather than as a description of today's browsers.

If you received a rejection, work from the reason in the notice: the Broken Functionality rejection walks through the most common functionality notice. Do not rebuild your TWA as a WebView only because of a browser bar. If your app came out of an AI builder, publishing a vibe-coded app on Google Play covers the full route from project to Play.

Frequently Asked Questions

The Bottom Line

Play Console menu labels are the fastest changing fact on this page. If the routes above no longer match your Console, look for Play app signing under Protected with Play, or search the Console for app signing.