How to Debug a Trusted Web Activity (TWA) on Android

Deploying a Progressive Web App (PWA) to the Google Play Store using a Trusted Web Activity (TWA) offers an efficient path to distribution. However, because a TWA runs within an optimised, fullscreen instance of the user system browser, standard web debugging techniques are not immediately accessible on the physical device. When visual bugs occur, or when the native shell fails to hide the URL bar, developer teams must utilise specific Android and browser debugging workflows.

This technical guide covers the essential methods for inspecting and debugging a TWA on Android. You will learn how to configure remote debugging, examine runtime service worker behaviour, and troubleshoot Digital Asset Links verification failures using the Android Debug Bridge (ADB) and system logs.

Setting Up Your Android Device for Remote Debugging

To inspect the web content running inside your TWA, you must establish a connection between your development machine and your test device. Remote debugging allows you to use your desktop browser developer tools to inspect the DOM, console outputs, and network requests occurring inside the packaged Android application.

First, enable developer options on your physical Android test device or emulator. Navigate to the system settings, locate the build number, and tap it seven times until the screen confirms developer mode is active. Return to the developer options menu and enable USB Debugging. Connect your device to your development computer using a high-quality USB cable. When prompted on the device, authorise the host computer to establish a debugging session.

Ensure your desktop browser is ready to interface with the device. If you use Google Chrome, open a new tab on your desktop and navigate to the inspection interface. This action exposes the active web targets running on connected devices.

chrome://inspect/#devices

With the physical device connected, launch your installed TWA application. On your desktop inspection tab, you will observe the connected device name followed by a list of active web pages and web views. Find the entry corresponding to your PWA URL and click inspect. A dedicated DevTools window will open, providing direct access to the application DOM, console, and performance profiles.

Inspecting Service Workers and Cache Storage

Because TWAs run on top of Chrome custom tabs, they rely entirely on your web-level service worker for offline capabilities and asset caching. When troubleshooting caching issues or push notifications inside your TWA, you must inspect the service worker context specifically.

Within the desktop DevTools window connected to your TWA, navigate to the Application panel. Here, you can verify if your service worker is active, inspect registered push subscriptions, and manually trigger sync events. Under the storage section, you can examine the Cache Storage API state to confirm that critical shell assets are available offline.

If updates to your PWA are not appearing within the TWA container, it is frequently due to aggressive service worker caching or a stalled update cycle. Use the DevTools Application panel to clear site data or force-update the service worker. This practice helps distinguish between a caching error and a compilation error in your packaged asset shell.

Troubleshooting Digital Asset Links Verification

The most common implementation error in TWA deployment is a visible URL address bar at the top of the application screen. This occurs when the Android operating system fails to verify the Digital Asset Links relationship between your web domain and your native Android app signature.

When the validation fails, Android falls back to standard Custom Tab behaviour, displaying the URL bar to ensure transparency and security for the user. To diagnose why this handshake failed, you must extract real-time validation logs directly from the device operating system using the Android Debug Bridge (ADB).

Connect your device, open your terminal, and run the following command to monitor the intent filter verification engine on your device:

adb logcat -d | grep -i intent_filter

For a highly targeted log analysis during launch, clear your logcat buffer and start the application shell. Observe the system logging output for verification outcomes. Look specifically for log statements originating from the verification services. A successful verification output generally resembles the following profile:

IntentFilterIntentOp: Verification SUCCESS for schema https on domain example.com

If the verification output reads as a failure, examine the following elements in your setup. First, verify that the SHA-256 fingerprint generated by Google Play App Signing matches the assetlinks.json file hosted on your server. If your app is enrolled in Google Play App Signing, the certificate fingerprint changes upon upload, meaning you must use the Google Play Console certificate, not your local upload key certificate.

Common TWA Debugging Scenarios and Solutions

When working with TWAs, specific patterns of failure emerge frequently during integration testing. Below is a diagnostics table highlighting common symptoms, root causes, and verification steps.

Using Command-Line Tools to Force Domain Verification

During the rapid development cycle, waiting for the Android OS to run its automatic domain verification checks can slow your progress. You can bypass this latency by manually forcing the verification of your package via ADB command line utilities.

To force the system to evaluate your Digital Asset Links configuration immediately, run the package manager command below. Replace the placeholder package with your actual Android application identifier:

adb shell pm verify-app --failures

You can also force the Android App Links system to clear its cache and execute an immediate verification run on modern Android versions using the following shell commands:

adb shell cmd package domain-verification-agent clear-rules --user all your.package.name

adb shell cmd package domain-verification-agent verify your.package.name

Executing these commands ensures that any updates made to your online assetlinks.json file are actively parsed by the device under test, saving substantial development time and eliminating caching variables.

Inspecting HTTP Response Headers

Ensure that your assetlinks.json file is being served over HTTPS, has a valid SSL certificate chain, and returns an HTTP status code of 200. The file must also return the correct MIME type. You can verify this using a terminal request command on your server endpoint:

curl -I https://yourdomain.com/.well-known/assetlinks.json

Look specifically for the Content-Type header. If it returns text/plain or application/octet-stream, modern Android security layers may reject the verification. The server must explicitly return application/json to be validated reliably by the underlying Chrome operating layer.