How to Test a TWA Locally Without Digital Asset Links

The Challenge of Local TWA Testing

When developing a Trusted Web Activity (TWA) to package your Progressive Web App for the Google Play Store, the most common stumbling block is the URL bar. By default, Android displays a browser URL bar at the top of your app unless a secure, bidirectional link is established between your Android application package and your web origin. This connection is validated using a Digital Asset Links JSON file hosted at your domain.

While this security model prevents malicious applications from spoofing legitimate websites, it poses a significant hurdle during active development. Setting up a public domain, obtaining an SSL certificate, and deploying updated Digital Asset Link files every time you want to test a local change is highly inefficient. Fortunately, you can bypass Digital Asset Link verification during development to test your TWA locally on physical devices or emulators using localhost or internal staging environments.

Method 1: Bypassing Verification via Android Chrome Flags

The most reliable way to test a TWA locally without deploying a public Digital Asset Links file is to instruct Chrome on your test device to skip verification for your specific development origins. This is achieved by passing command-line arguments to the Chrome browser running on Android. Because TWAs rely on the system installation of Chrome (or other Custom Tabs providers), overriding Chrome flags directly alters how the TWA wrapper behaves.

To configure these overrides, you must use the Android Debug Bridge (ADB) tool on your development machine. Ensure your test device is connected with USB debugging enabled, or that your Android Virtual Device (AVD) emulator is running. Execute the following command to instruct Chrome to ignore asset link verification for your development origin:

adb shell "echo '_ --disable-digital-asset-link-verification-for-origins=https://your-local-ip:port,http://localhost:port' > /data/local/tmp/chrome-command-line"

After writing this command-line file to the device, you must restart Chrome to apply the flags. Run the following command to force-close Chrome:

adb shell am force-stop com.android.chrome

When you next launch your TWA application, Chrome will bypass the validation handshake for the specified origins. The URL navigation bar should disappear, allowing you to preview the app in full-screen mode exactly as your production users will see it.

Method 2: ADB Reverse Port Forwarding for Localhost

If your Progressive Web App is running on your development machine at http://localhost:3000 or http://localhost:8080, an Android device or emulator will not naturally resolve "localhost" to your computer. Instead, it will attempt to resolve localhost internally within the Android operating system, resulting in a connection error.

You can resolve this by setting up ADB reverse port forwarding. This routing mechanism instructs the Android system to forward network requests made on a specific port of the mobile device back to a specific port on your development computer over the USB or emulator connection. Run the following command in your terminal:

adb reverse tcp:3000 tcp:3000

With this port forward active, navigating to http://localhost:3000 inside the Android emulator or on the connected USB device will load the PWA running on your development server. When combined with the command-line flags from Method 1, you can test a fully integrated, full-screen TWA directly against your live development server with hot-reloading active.

Method 3: Secure Local Tunnels for Multi-Device Testing

In complex testing scenarios, such as testing across multiple physical devices on a Wi-Fi network or sharing progress with external stakeholders, ADB reverse port forwarding may be insufficient. In these cases, using a local secure tunneling tool is the most efficient alternative. These tools expose your local development server to a secure, public HTTPS URL.

When utilizing a secure tunnel, you must ensure your tunnel provider generates a stable or at least consistent domain name. Because Digital Asset Links rely heavily on domain validation, generating a new, randomised tunnel subdomain every time you restart your tunnel will require constantly updating your TWA's configuration. To avoid this, configure your tunnel client to use a reserved subdomain where possible.

Verifying the Local TWA Environment

Once you have configured your bypass mechanism and launched the TWA wrapper on your test device, you must confirm that the application is running in a true Trusted Web Activity context. A successful local deployment will meet several visual and technical criteria:

• No URL Bar: The browser chrome, including the domain name display, lock icon, and refresh buttons, must be completely hidden.
• Proper Context: Inspect the application using Chrome DevTools on your computer (via chrome://inspect). Your app should show up as a target under your connected device, allowing you to debug console logs, network requests, and service workers.
• System Integration: Native features mapped within your manifest, such as status bar customisations and display orientation limits, should be respected by the wrapper shell.

If the URL bar remains visible after applying these steps, verify that your command-line file was written to the correct path on the Android device. Some modified versions of Android or alternative browsers may read command-line parameters from different directories, or require you to enable developer options inside the mobile browser settings menu to allow command-line execution.