Setting Up Android Emulators for Testing TWAs

Understanding TWA Dependencies on the Android Emulator

To run a Trusted Web Activity (TWA) correctly, the target Android device must have a modern web browser installed that supports Chrome Custom Tabs. On physical consumer devices, Google Chrome or another compatible browser is almost always present. However, inside the developer environment of Android Studio, standard Android Virtual Devices (AVD) behave differently. Many default system images lack the necessary Google applications, falling back to a bare-bones Android System WebView engine.

When a TWA wrapper application detects that no Custom Tabs provider is available on the device, it automatically falls back to an embedded WebView instance. While this ensures your app still opens, it bypasses the performance optimisations, shared cookie storage, and advanced web API support that make TWAs superior. To test your PWA exactly as it will run for production users on Google Play, you must set up an emulator that accurately reproduces the native browser environment.

Selecting the Correct System Image in Android Studio

When creating an Android Virtual Device in Android Studio, you are prompted to select a system image. System images are categorised by their architecture, API level, and Google service integrations. Selecting the wrong image is the primary reason developers struggle to test TWAs locally.

To test a TWA, you must select an image that includes the Google Play Store icon in the target column. This guarantees that the emulator includes Google Play Services, Google Chrome, and the ability to update Chrome to the latest version.

Step-by-Step AVD Creation

• Open Android Studio and navigate to the Device Manager.
• Click Create Device to open the hardware selection screen.
• Choose a hardware profile that displays the Google Play icon in the Play Store column (for example, Pixel 5 or Pixel 6).
• Click Next and select a system image. Choose an image under the Recommended tab that matches your targeted API level and displays Google Play in its description.
• Click Next, verify your settings, and click Finish to create the emulator.

Accessing and Updating Chrome on the Virtual Device

Once you boot your new emulator, you must ensure that Google Chrome is active and updated. Outdated Chrome versions on older system images can cause inconsistencies during testing. Since you selected a system image with Google Play Services, you can update Chrome directly.

Launch the emulator and open the Google Play Store app. Sign in with a valid Google account. Once signed in, search for Google Chrome and check if an update is available. Upgrading Chrome to the latest version ensures that the underlying Custom Tabs implementation matches the current behaviour of production consumer devices.

Bypassing Digital Asset Links for Localhost Testing

Under production conditions, a TWA requires Digital Asset Links to verify ownership of the web domain. Without this verification, the TWA displays the address bar at the top of the screen, ruining the native app experience. When testing on a local emulator, verifying your domain via a public assetlinks.json file is impractical, especially if your PWA is running on a local development server like localhost:3000.

To bypass Digital Asset Links verification on your emulator and test your app without the URL address bar, you must instruct Chrome on the virtual device to bypass verification for your package and local development origin. This is achieved using the Android Debug Bridge (ADB) command-line tool.

First, ensure your emulator is running and connected. Run the following command in your terminal to write a configuration file to the emulator's temporary storage, substitution your package name and local port:

adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"http://localhost:3000\"' > /data/local/tmp/chrome-command-line"

Next, you must modify the permissions of this file to allow Chrome to read it during startup:

adb shell chmod 555 /data/local/tmp/chrome-command-line

After writing the configuration file, force stop Chrome to ensure it reads the command-line flags upon its next launch:

adb shell am force-stop com.android.chrome

Now, when you compile and launch your TWA package onto the emulator, it will run the local development server URL in full-screen mode, completely hiding the address bar as if it were fully verified.

Hooking Up Chrome DevTools for Remote Inspection

Once your TWA is running on the emulator, you can inspect it, modify CSS, debug JavaScript, and audit network calls using Chrome DevTools on your host computer. This provides an identical debugging experience to standard desktop web development.

Open Google Chrome on your host computer. In the URL bar, type the following address to open the device inspection panel:

chrome://inspect/#devices

You will see a list of connected devices. Your running Android emulator will be visible, displaying the active tab running inside your TWA. Click the Inspect button next to the target URL to launch a dedicated DevTools window targeting your application. From here, you can debug service worker registration, view IndexedDB storage, and track console errors in real time.