Use related_applications in TWA Web Manifests

When you publish your Progressive Web App on the Google Play Store using a Trusted Web Activity (TWA), you create two entry points for your users on Android devices. They can install your app directly from the Google Play Store as a native-feeling Android application, or they can visit your website via Chrome and install it as a desktop or mobile PWA through the browser install banner.

This dual installation availability creates an architectural challenge known as the duplicate prompt problem. If a user visits your website in a mobile browser, Chrome may prompt them to install the PWA, unaware that your fully packaged app is already available on their device or on the Google Play Store. To prevent this confusing user experience, you must configure your Web App Manifest using the related_applications and prefer_related_applications properties.

The Purpose of related_applications

The related_applications member of the Web App Manifest is an array of objects that informs the browser about alternative native applications that serve the same purpose as your web application. This property acts as a handshake between the web platform and native stores, allowing browsers to coordinate installation options.

By listing your Google Play Store package details inside this array, you tell Android devices that your website is directly associated with a specific Google Play app. This mapping allows the system to suppress web-based installation prompts, direct users to your official Google Play listing, or detect if the user has already installed your TWA app.

The Role of prefer_related_applications

Simply listing your application in the related_applications array is not enough to change default browser behavior. You must also include the prefer_related_applications boolean property and set its value to true.

When prefer_related_applications is set to true, mobile browsers such as Chrome will actively change their installation flow. Instead of prompting the user to install the web app, Chrome will check the local device to see if your Google Play TWA is already installed. If it is not installed, and the user triggers an installation event, the browser can automatically route the installation request to the Google Play Store rather than installing the lightweight standalone web shortcut.

Configuring the Manifest JSON

To implement this setup, you must update your web app manifest file, which is typically named manifest.json or site.webmanifest. You need to add the two specific keys alongside your standard properties like name, short_name, and start_url.

Below is an example of a properly configured Web App Manifest highlighting the correct placement and structure of the application references:

{ "name": "My SaaS Application", "short_name": "SaaSApp", "start_url": "/", "display": "standalone", "prefer_related_applications": true, "related_applications": [ { "platform": "play", "id": "com.example.saasapp", "url": "https://play.google.com/store/apps/details?id=com.example.saasapp" } ] }

In this block, the platform property must be set to play. The id property must match your exact Google Play Store package name, which is also referred to as your application ID. The url property points to your listing on the web version of the Google Play Store.

How Chrome Evaluates Your Manifest

Understanding the exact logic path the Android operating system and Chrome use helps you debug installation issues. The checklist below outlines the steps the browser takes when a user lands on your site:

• The browser downloads and parses your site manifest.
• It detects that prefer_related_applications is set to true.
• The browser queries the local Android PackageManager to check if an app with the specified package name (id) is installed on the device.
• If the app is found on the device, Chrome suppresses all ambient badge prompts, install buttons, and standard PWA install headers.
• If the app is not found on the device, the browser allows installation, but prioritises directing the user to your Google Play Store listing when they interact with install elements.

Key Properties Reference Table

Ensure you format your related_applications entries correctly. The table below lists the permitted keys for the Google Play platform configuration:

Verifying the Handshake

To verify that your web manifest configuration is working alongside your installed TWA, you can use remote debugging tools. Connect an Android device containing your installed TWA to your development computer and navigate to your website in Chrome.

Open Chrome DevTools on your computer, inspect the connected device, and view the Application tab. Under the Manifest section, verify that the prefer_related_applications field is marked as true and that your Google Play package registration details are correctly displayed in the related applications section. If the setup is correct, you should notice that the standard browser install prompt is no longer visible on your mobile screen.

Important Security Notes

For security reasons, Chrome will only suppress web installation prompts if a valid cryptographic trust relationship exists between your website and your Google Play app. This relationship is verified using your Digital Asset Links file, which must be uploaded to your web server at the /.well-known/assetlinks.json path.

If you configure your manifest to prefer your Google Play app but fail to upload a valid assetlinks.json file containing your Android app signing key signatures, Google Chrome will ignore your manifest instructions and continue to display web installation prompts. Always ensure both files are correctly synchronised to maintain a clean, professional user experience.