Tracking Google Play Install Referrers in a TWA

Marketing attribution is vital for understanding your return on investment when running acquisition campaigns. When publishing a Progressive Web App to the Google Play Store using a Trusted Web Activity, tracking how users found your app becomes more complex. Standard web analytics tools easily capture UTM parameters when a user clicks a link on the web, but this chain is broken when a user transitions through the Google Play Store app installation flow.

To solve this, Google provides the Play Install Referrer API. For standard native applications, this API retrieves referrer details directly from the Play Store application after installation. For a PWA running inside a TWA wrapper, you must bridge this native API data into your web application context to measure your store campaigns accurately.

How the Installation Referrer Flow Works

When a user clicks on an ad or a promotional link pointing to your Google Play Store listing, the store captures referral metadata. This metadata can contain campaign sources, mediums, keywords, or unique tracking identifiers. When the user clicks install, the Google Play Store app stores this referrer payload locally on the device.

When the user opens your installed TWA application for the first time, your native Android wrapper must query the local Google Play service using the Play Install Referrer Client. Once the wrapper retrieves this string, it must append the referrer details to the launch URL of your TWA before launching the full-screen browser session.

The sequence follows these distinct steps:

• The user clicks an external link containing referral data and is redirected to Google Play.
• The user installs your application.
• Upon the first boot, the Android launcher activity initializes the Play Install Referrer Client.
• The client retrieves the raw referrer string from the Play Store service.
• The launcher appends this raw string to your web app start URL as query parameters.
• Your web-based analytics script reads these parameters on load.

Retrieving the Referrer inside the Android Wrapper

To implement this, your Android TWA wrapper must include the Google Play Install Referrer library dependency in its build configuration. The native Java or Kotlin launcher code then executes an asynchronous query to fetch the referrer parameters.

Once the connection is established, the application checks if it is the first launch of the application. If it is, the native wrapper reads the referrer details, formats them into a URL-friendly query string, and updates the shared preferences so that the query is only executed once. The retrieved string is then appended to the main launch intent.

For example, if your standard TWA start URL is configured as your domain with a launch parameter, the wrapper can dynamically modify it to append the retrieved marketing parameters:

https://example.com/?utm_source=playstore&utm_campaign=winter_sale

This dynamic appending is what enables your web code to access the native acquisition data transparently.

Processing Referrer Parameters in JavaScript

Once the TWA successfully passes the referrer details to the launch URL, your web application must capture and process them. Since the first-page load will contain these query parameters, your JavaScript should parse them immediately and send them to your analytical endpoints.

You can use the following approach to safely read and persist referrer values:

const urlParams = new URLSearchParams(window.location.search);

const referralSource = urlParams.get('utm_source');

const campaignName = urlParams.get('utm_campaign');

if (referralSource) {

localStorage.setItem('install_referrer_source', referralSource);

}

if (campaignName) {

localStorage.setItem('install_referrer_campaign', campaignName);

}

Storing these values in local storage ensures that even if your web analytics package initialization is delayed or if the user registers an account several sessions later, you can still associate the conversion with the original installation campaign source.

Testing Install Referrers Locally

Testing your integration without publishing to the live Play Store is essential for verified deployments. You can simulate an installation referrer broadcast using the Android Debug Bridge on a connected test device or emulator.

By sending an intent broadcast via the command line, you can test how your Android wrapper handles the payload and check if it successfully passes the variables to your PWA start URL. You can use this ADB command template to trigger a test broadcast:

adb shell am broadcast -a com.android.vending.INSTALL_REFERRER -n your.package.name/your.referrer.ReceiverClassName --es referrer "utm_source=test_source&utm_campaign=test_campaign"

Running this broadcast simulates the Google Play Store delivery mechanism, allowing you to watch your Android application logs and verify that the target URL resolves with your test parameters attached.

Attribution Strategies for TWA Apps

When measuring user acquisition, different analytics strategies have distinct benefits and trade-offs. The table below outlines how web attribution compares to native and hybrid approaches in a TWA context.

For most SaaS founders and web developers, the hybrid approach is highly recommended. It avoids the bloat of native SDK integrations while maintaining excellent data fidelity by feeding the native installation source directly into your existing web tracking pipelines.