Hiding PWA Install Prompts Inside an Android TWA

When a user installs your Progressive Web App (PWA) directly from the Google Play Store via a Trusted Web Activity (TWA), they expect a seamless native app experience. However, a common and unprofessional user experience issue occurs when the underlying web application continues to display custom "Install our App" banners, headers, or pop-ups. Since the user has already installed the app from the app store, these prompts are redundant and confusing.

The Cause of Duplicate Install Prompts

By default, web browsers on Android like Google Chrome track whether a PWA is installed on the device. However, Chrome may not automatically suppress the standard web install event inside a TWA wrapper unless you explicitly configure your web application to detect the wrapper environment. This means the browser will still fire the beforeinstallprompt event inside your TWA.

If your web app listens for this event to display a custom install button or floating banner, that banner will render inside your Google Play application. To prevent this, you must programmatically detect that the web application is running inside a TWA and suppress the installation UI accordingly.

How to Detect a TWA Environment

To selectively hide install prompts, you must first reliably determine if your web app is running inside the TWA wrapper. There are three primary methods to achieve this, each with its own advantages depending on your build setup.

Method 1: Checking the Display Mode Relation

The cleanest approach is to use CSS media queries or JavaScript to check the display mode. When running inside a TWA, the display mode is typically reported as standalone or fullscreen. However, because standard web-installed PWAs also use standalone, this method is best combined with a more specific identifier.

Method 2: Appending a Query Parameter to the Start URL

A highly reliable method is to append a unique query parameter to the start_url inside your TWA configuration. When building your TWA with PWAtoApp, you can configure the launcher activity to open your PWA with a query parameter such as utm_source=twa or platform=android-twa.

Using JavaScript, you can read this parameter on launch and store a flag in sessionStorage or localStorage to persist the detection across page navigations:

const urlParams = new URLSearchParams(window.location.search);
const isTwa = urlParams.get('platform') === 'android-twa' || localStorage.getItem('is_twa') === 'true';
if (urlParams.get('platform') === 'android-twa') {
  localStorage.setItem('is_twa', 'true');
}

Method 3: Checking the Document Referrer

When a TWA launches, the initial document referrer from the Android system often contains the package name or a specific origin format. You can check document.referrer for the presence of your Android package identifier, though this is less consistent than using a dedicated query parameter.

Suppressing the beforeinstallprompt Event

Once you have established a reliable detection mechanism, you can write the logic to intercept and disable the browser-level installation prompt.

Normally, browsers fire the beforeinstallprompt event when the PWA meets the installation criteria. To hide your custom UI and prevent the browser prompt, you must call preventDefault() on the event object. Here is the implementation:

let deferredPrompt;
window.addEventListener('beforeinstallprompt', (e) => {
  if (isTwa) {
    e.preventDefault();
    return false;
  }
  deferredPrompt = e;
  showCustomInstallBanner();
});

In this code, if the detection helper determines that the application is running inside a TWA, the event is immediately cancelled and the function exits, preventing the custom install banner from rendering to the user.

Hiding Existing Static Promotional Elements

In addition to dynamic banners triggered by the beforeinstallprompt event, your web app might have hardcoded promotional links, footer banners, or menu items pointing to your app's installation page. These also need to be hidden.

You can manage this dynamically using CSS utility classes. By applying a class to your layout elements, you can hide them entirely when the TWA environment is detected:

if (isTwa) {
  document.body.classList.add('twa-env');
}

In your global stylesheet, you can then target these promotional elements:

.twa-env .pwa-install-banner,
.twa-env .install-prompt-button {
  display: none !important;
}

Comparing Detection Methods

The following table outlines the trade-offs of each detection method to help you choose the best implementation for your setup:

Testing Your Implementation

To verify that your installation prompts are successfully hidden, you should test the application on an Android device or emulator. First, run the web application in a standard mobile browser to ensure that the installation banner behaves as expected for web users.

Next, compile your TWA with your custom query parameter configured in the start URL. Install the generated APK on your testing device. When launching the app through the TWA launcher, check that no custom banners, prompts, or download UI elements appear. Inspecting the webview using Chrome DevTools remote debugging will allow you to verify if the isTwa evaluation returned true.