Fixing Digital Asset Links: Why the TWA URL Bar Persists

When launching a Progressive Web App (PWA) packaged inside an Android Trusted Web Activity (TWA), the browser UI should disappear completely, providing a full-screen, native-feeling application experience. However, developers frequently encounter an issue where the Chrome address bar remains visible at the top of the interface. This persistent URL bar is Chrome's default fallback security mechanism. It indicates that the handshake between the Android package and the web origin has failed.

Understanding the Verification Handshake

For the browser to grant full-screen access, a digital signature match must occur. This process relies on Digital Asset Links. When the TWA launches, the underlying browser engine reads the application ID and the SHA-256 certificate fingerprint of the APK. It then sends an HTTPS request to your web origin to retrieve a JSON file located at a specific path: /.well-known/assetlinks.json.

If the information inside this hosted JSON file does not exactly match the cryptographic signature of the running Android application, verification fails. Chrome determines that the application owner does not own the web origin and falls back to a restricted Custom Tab view, which includes the URL address bar and a lock icon to protect the user from phishing attempts.

The Core Reason: Google Play App Signing vs Local Signatures

The single most common reason for verification failure is a fingerprint mismatch caused by Google Play App Signing. When you build and test your TWA locally, you sign the APK with a local upload key or debug key. However, when you upload your Android App Bundle (AAB) to the Google Play Console, Google replaces your upload signature with a unique App Signing Key generated on their servers.

This means your local APK and the final APK downloaded by your users from the Google Play Store have entirely different SHA-256 fingerprints. To fix this, you must configure your assetlinks.json file to support both keys.

You can locate the correct fingerprints by taking the following steps:

• Log in to your Google Play Console.
• Select your application from the dashboard.
• Navigate to Setup and click on App Integrity.
• Locate the App signing key certificate section.
• Copy the SHA-256 certificate fingerprint displayed there.
• Ensure you also include the SHA-256 fingerprint of your local Upload key certificate, which is listed lower down on the same page.

Server and Header Configurations

Even if your SHA-256 fingerprints are mathematically correct, the web server hosting the configuration file might block successful verification. Google's verification client is highly sensitive to server configurations, security protocols, and caching mechanisms. Review the following system requirements:

• Content-Type Header: The web server must serve the assetlinks.json file with the application/json MIME type. Serving it as text/plain or application/octet-stream will cause verification to fail immediately.
• HTTP Status Code: The request must return an explicit HTTP 200 OK status code. Redirection codes such as 301, 302, or 307 are not followed by the Android system verification client. The file must exist natively at the exact canonical path.
• SSL/TLS Configuration: The domain must be served over a secure, valid HTTPS connection. Self-signed SSL certificates, invalid certificate chains, or expired certificates will block the handshake.
• CORS and Firewall Rules: Ensure that your web server or web application firewall does not block automated crawlers or requests targeting the .well-known directory.

Structuring the JSON File Correctly

The structure of the assetlinks.json file must be a valid JSON array containing one or more statement blocks. A single syntax error, such as a missing comma or an unescaped character, invalidates the file. The file should be structured as follows:

[ { "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.twa", "sha256_cert_fingerprints": ["AA:BB:CC:DD...YOUR_PLAY_STORE_SHA_256", "11:22:33:44...YOUR_LOCAL_UPLOAD_SHA_256"] } } ]

Ensure that all characters in the SHA-256 fingerprint are capitalised and separated by colons. The package name must match the application ID defined in your TWA build configuration.

How to Test and Diagnose Failures

Because Android caches Digital Asset Links verification results to conserve bandwidth and battery life, testing changes can be difficult. If a failure is cached, updating your server will not instantly remove the URL bar on your testing device.

To bypass the local cache during development, you can configure command-line flags in Chrome on your testing device to bypass Digital Asset Links verification for specified domains. This allows you to test the visual layout of your full-screen app even before deploying your JSON configuration to a production server.