Configuring TWA Subdomains and Multiple Origins

The Multi-Origin Challenge in Trusted Web Activities

A Trusted Web Activity (TWA) provides a seamless way to package a Progressive Web App (PWA) as an Android application. Under the hood, a TWA runs within a specialised instance of the user's default browser (typically Google Chrome) that hides the browser interface. However, this seamless visual integration depends entirely on a strict security handshake called Digital Asset Links.

By default, a TWA is configured to trust a single main origin, such as your primary domain. If a user navigates away from this primary origin to a subdomain or another external domain, the security handshake fails. When this happens, the TWA immediately displays the standard browser URL bar at the top of the screen. For SaaS platforms, enterprise systems, and multi-tenant applications that distribute their workloads across subdomains, this default behaviour degrades the native look and feel of the application.

To maintain a fully immersive, fullscreen experience across all parts of your application, you must explicitly configure your TWA to trust multiple subdomains and alternative origins. This requires coordinating configurations inside your Android project and deploying Digital Asset Links files across all participating servers.

Understanding the Security Handshake for Alternative Origins

The core mechanism that governs whether the browser URL bar is shown inside a TWA is the verification of Digital Asset Links. When your Android application boots up and launches the TWA, the underlying browser reads the target URL. It then requests a special verification file located at the well-known path of that exact domain.

This verification must occur for every distinct origin the user visits within the application shell. If your app starts on one domain and navigates to another, the browser triggers a separate verification call for the new domain. If the new domain does not host a valid verification file matching the application's signing certificate, or if the Android application package does not list the new domain as a trusted source, the URL address bar is instantly restored to protect the user from phishing attacks.

An origin in web security terms is defined by the combination of the scheme, host, and port. This means that your primary domain, any of its subdomains, and any companion domains are all treated as completely separate origins by the Android security framework. They must each be handled individually in your TWA configuration.

Deploying Digital Asset Links Across All Domains

The first step in establishing trust across multiple subdomains is deploying the Digital Asset Statement file to every single web server involved in the navigation flow. This file must be served over a secure HTTPS connection and must be accessible without any redirects.

For every origin, you must host the identical assetlinks.json file at the following path:

/.well-known/assetlinks.json

This JSON file lists the package name of your Android application and the SHA-256 fingerprint of your app signing key. If you are using Google Play App Signing, you must ensure you use the SHA-256 fingerprint provided in the Google Play Console, rather than your local upload key fingerprint.

If you have a primary domain and two subdomains, you must ensure that all three web servers respond to the well-known path with a valid assetlinks.json file. For example, the file must be served properly on:

• Primary Domain: https://example.com/.well-known/assetlinks.json
• Subdomain One: https://app.example.com/.well-known/assetlinks.json
• Subdomain Two: https://auth.example.com/.well-known/assetlinks.json

These files must be served with the correct Content-Type header of application/json. If the server returns a text plain header or redirects the browser to a login screen, the validation will fail, and the navigation bar will appear within the TWA.

Configuring the Android Manifest for Multiple Origins

Once your web-side assets are correctly configured, you must update the Android package configuration to declare these additional origins as trusted targets. This is done by modifying your build files and the AndroidManifest.xml file.

In a standard TWA build, your build file defines a default relation. To add multiple origins, you must configure your asset statements to contain an array of objects rather than a single entry. The Android build system handles this by compiling these declarations into a resource string.

Your application resource file (typically strings.xml or compiled directly during the build) needs to define the asset statements. This resource maps the relationship between your Android app package and the target domains. Below is the structure of how multiple domains are declared in the asset statements configuration:

In your resource files, the asset statements must encompass all trusted sites. This tells the Android operating system that your app is authorized to handle intent filters and open these web links natively within the TWA. Below is an example of the configuration markup used to bind multiple domains together inside the asset resource statement:

[ { "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "web", "site": "https://example.com" } }, { "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "web", "site": "https://app.example.com" } } ]

This array links your app to both your main site and your subdomain. If you have an authentication server or a separate static asset origin, you must append them to this list as separate objects in the JSON array.

Configuring the TWA Intent Filters

In addition to specifying the asset statements, the Android manifest must contain intent filters for each origin. Intent filters dictate which web links should trigger the application when clicked by a user on their device, such as in an email client or a messaging app.

Within the activity node of your TWA inside the AndroidManifest.xml file, you should list intent filters for all domains you wish to handle. If you only specify the intent filter for the main domain, links pointing to the subdomains will open in the system web browser instead of launching the TWA.

Each intent filter requires an action, a category, and a data tag containing the host scheme and the host name. You can declare multiple data tags within a single intent filter to capture your subdomains, ensuring that all internal navigation loops correctly inside the native wrapper.

Handling Wildcard Subdomains and Multi-Tenant SaaS

For SaaS applications that provision a unique subdomain for every customer (for example, client1.yourplatform.com, client2.yourplatform.com), registering every individual origin inside the Android Manifest statically is impossible. The Google Play Store requires a static compilation of the Android package, which cannot be dynamically updated as new customers sign up.

To manage wildcard subdomains in a TWA, you must employ a hybrid strategy. Since Digital Asset Links do not support wildcard syntax (such as *.yourplatform.com), you cannot validate an infinite number of subdomains directly through static compilation. Instead, you should design your TWA navigation flow to route critical native features through a centralized, single domain.

A common architectural solution is to run the core authenticated interface on a single main origin, such as app.yourplatform.com, and pass tenant identifiers as secure path variables or query parameters rather than using subdomains. If subdomains are an absolute requirement for branding, you will need to handle the initial sign-in on a central, validated domain before redirecting the user to an in-app browser view or managing state across subdomains using deep linking APIs.

Testing the Multi-Origin Verification

To verify that all origins are configured correctly and that the URL bar is successfully suppressed across all transitions, you must test the app on a physical device or emulator. Because verification results are heavily cached by the Android system, testing can sometimes produce false positives.

To test cleanly, always uninstall the previous version of the app from your testing device. You can use Chrome DevTools on your computer to inspect the running TWA on your connected device. If you see a warning icon or if the URL bar appears during a transition to a subdomain, open the Chrome system logs on the device using Android Debug Bridge (ADB) to inspect the specific verification error code. Common errors include failing to fetch the assetlinks.json file due to a security certificate mismatch or server-side redirects that interrupt the handshake process.