Customising the User-Agent in a Trusted Web Activity

When delivering a Progressive Web App inside an Android wrapper using a Trusted Web Activity, you will often need to know whether a user is visiting from their standard mobile browser or from your installed Google Play store application. Identifying this context allows your application to deliver an optimized experience, such as hiding browser install banners, modifying UI layouts, or adapting analytics tracking.

Why Identify TWA Traffic

A common error when converting a web application to an Android package is treating all mobile visitors identically. Users who have gone through the process of downloading your app from the Google Play Store expect an experience that feels deeply integrated with their device. Showing these users a banner that prompts them to install the web app is confusing and looks unpolished. Beyond cosmetic changes, knowing your traffic source is vital for attribution modeling and isolating performance metrics between organic web visitors and app users.

The Limits of Default Detection Methods

Developers sometimes rely on alternative methods to detect app traffic, but these approaches have notable limitations. For instance, passing a query parameter such as custom source tags on the entry URL works when the application first launches, but this parameter is quickly lost as the user navigates to other pages. Relying on the referrer header can also be unreliable, as internal page navigations will overwrite the original referral source. This is why modifying the User-Agent string is the most robust and industry-standard method for identifying Trusted Web Activity execution environments.

How to Append a Custom String to the User-Agent

In a Trusted Web Activity, the underlying browser engine is Google Chrome or another compatible Custom Tabs provider. You cannot entirely replace the User-Agent string, nor should you, as doing so would break feature detection on your web server. Instead, the correct approach is to append a custom suffix to the existing User-Agent. This preserves all the browser capabilities and version information while giving your server a clear identifier to read.

To configure this, you need to pass the custom User-Agent configuration through your Android build files. If you are using standard build systems or configuring your launcher activity programmatically, you can define metadata in your build config or manifest file. Here is how you configure this in your Android development workflow.

Modifying the Build Configuration

If your build system supports it, you can declare a custom User-Agent suffix in your local configuration. This appends your specified identifier to Chrome's default User-Agent string whenever the TWA is active.

// Example build.gradle configuration segment android { defaultConfig { manifestPlaceholders = [ hostName: "example.com", defaultUrl: "https://example.com", launcherName: "MainActivity", additionalUserAgent: "MyTWAApp" ] } }

When this is compiled, the underlying Trusted Web Activity client will read the additionalUserAgent value and append it to the outgoing browser header. The resulting User-Agent string will look similar to this:

Mozilla/5.0 (Linux; Android 13; Pixel 6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Mobile Safari/537.36 MyTWAApp

Detecting the Custom User-Agent on the Web Side

Once your TWA is compiled with the custom suffix, your web server and client-side JavaScript can easily check for its presence.

Client-Side Detection using JavaScript

To toggle interface elements or handle user state on the frontend, you can run a simple regular expression check against the window navigator string.

// Client-side detection function function isRunningInTWA() { return navigator.userAgent.includes('MyTWAApp'); } if (isRunningInTWA()) { // Hide PWA install prompts document.getElementById('install-banner').style.display = 'none'; console.log('App running in native TWA mode'); }

Server-Side Detection in PHP

Detecting the client environment server-side allows you to prevent certain scripts from rendering entirely, which reduces load times for mobile app users.

// PHP server-side detection $userAgent = $_SERVER['HTTP_USER_AGENT'] ?? ''; $isTWA = strpos($userAgent, 'MyTWAApp') !== false; if ($isTWA) { // Apply server-side logic specifically for the Android App }

Comparing TWA Identification Methods

While appending a custom string to the User-Agent is highly recommended, it is useful to understand how it compares to other identification techniques.

Google Play Policy Considerations

When customising the User-Agent, it is critical to adhere to Google Play Developer policies. You must not use this identifier to serve an entirely different website or to bypass Google Play rules. The primary purpose of identifying the TWA should be to optimise the user interface, disable redundant installation reminders, or track analytics. Using a custom User-Agent to alter the application's core functionality or to hide compliance issues during the app review process can lead to app rejection or removal from the store.

Testing Your Custom User-Agent

Before publishing your updated AAB to production, you should verify that the User-Agent modification is working correctly. You can do this by running your app in an Android emulator or on a physical test device with USB debugging enabled. Connect the device to your computer, open Google Chrome, and navigate to chrome://inspect. Find your running Trusted Web Activity under the device list, open the inspector, and log the navigator.userAgent property in the console to confirm that your custom suffix is successfully appended.