Appy
← Back to Blog
Guide

How to Test the Google Play Install Referrer on a Real Device

A build from Android Studio never has an install referrer, so most tests read an empty value and stop there. How to get a real one: an encoded Play URL, an internal testing track, a fresh install and a Kotlin read on first launch, plus what each empty or odd result means.

Appy•November 13, 2026•7 min read

Links that carry a referrer to Google Play by themselves

  • One link for Google Play, the App Store and your website
  • Campaign and link name kept through the install
  • Free plan, no credit card
Create my free link

Short answer

How do you test the Google Play Install Referrer on a real device?

Publish the build to an internal testing track, uninstall the app from a test phone, open a Play URL with a URL-encoded referrer on that phone, install from the Play page and read the value with the Play Install Referrer Library on the first launch. A build installed from Android Studio or adb never carries a campaign referrer.

Key takeaways

  • The referrer is fixed for an install and kept for 90 days; to test again, uninstall and reinstall from the Play URL.
  • Encode the value so = and & stay inside the referrer parameter, and keep it to 512 characters or fewer.
  • utm_source=google-play&utm_medium=organic means the install didn’t come through your link.

The short answer

Google Play only hands over a referrer for installs that come through the Play Store app. A debug build installed from Android Studio or with adb has no install from Play behind it, so there is nothing campaign-specific to read.

To test it for real, publish a build to an internal testing track, uninstall the app from a test phone, open a Play URL with an encoded referrer on that phone, install from the Play page that opens, and read the value on the first launch. The whole loop takes about ten minutes once the track is set up.

The Play URL you test with

A normal store link with one extra parameter.

https://play.google.com/store/apps/details?id=com.example.myshop&referrer=utm_source%3Dqa_test%26utm_campaign%3Dreferrer_check

  1. https://play.google.com/store/apps/details

    Store page

    The standard Google Play address for an app.

  2. ?id=com.example.myshop

    Package

    Your application ID, exactly as in the Play Console.

  3. &referrer=

    Referrer parameter

    Everything after it is handed to your app after the install.

  4. utm_source%3Dqa_test%26utm_campaign%3Dreferrer_check

    Encoded value

    utm_source=qa_test&utm_campaign=referrer_check, URL-encoded so its = and & stay inside the referrer. Google asks for 512 characters or fewer.

Use a value you will recognise in the logs. If it arrives intact, encoding and delivery both work.

Test it end to end

01

Add the library and the read

Add com.android.installreferrer:installreferrer:2.2 and call the read on the first launch, as in the code below. Log the value so you can see it with logcat.

02

Publish to internal testing

Upload the build to the internal testing track in the Play Console and add your Google account as a tester. Internal tests take up to 100 testers, and new builds reach them within minutes; the very first publication can take a few hours.

03

Join the test on the phone

Open the opt-in link from the Testers tab with the same Google account that is signed in to the Play Store app on the test phone.

04

Uninstall the app

The referrer is fixed for an install and doesn’t change until the app is reinstalled. Remove any earlier copy, including the one Android Studio put there.

05

Open the Play URL on the phone

Tap it in Chrome, in a chat or from a QR code, so it opens the Play Store app on that phone. Installing from play.google.com in a desktop browser is a different path; test the one your users take.

06

Install and open the app

Install from the Play page that opened, then launch the app once. Watch adb logcat for the referrer and the two timestamps.

07

Compare with what you sent

You should see utm_source=qa_test&utm_campaign=referrer_check, a click time and an install start time. To test again, uninstall and start from the Play URL.

Read it on the first launch

Kotlin, based on Google’s sample. It reads the referrer once, logs it and closes the connection.

build.gradle.kts

dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
}

InstallReferrer.kt

import android.content.Context
import android.util.Log
import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerClient.InstallReferrerResponse
import com.android.installreferrer.api.InstallReferrerStateListener

fun readInstallReferrerOnce(context: Context) {
    val prefs = context.getSharedPreferences("install_referrer", Context.MODE_PRIVATE)
    if (prefs.getBoolean("read", false)) return

    val client = InstallReferrerClient.newBuilder(context).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(responseCode: Int) {
            when (responseCode) {
                InstallReferrerResponse.OK -> {
                    val details = client.installReferrer
                    Log.d("InstallReferrer", "referrer=${details.installReferrer}")
                    Log.d("InstallReferrer", "clickTime=${details.referrerClickTimestampSeconds}")
                    Log.d("InstallReferrer", "installBegin=${details.installBeginTimestampSeconds}")
                    prefs.edit().putBoolean("read", true).apply()
                }
                InstallReferrerResponse.FEATURE_NOT_SUPPORTED ->
                    Log.d("InstallReferrer", "Play Store app doesn't support the API")
                InstallReferrerResponse.SERVICE_UNAVAILABLE ->
                    Log.d("InstallReferrer", "Play Store service unavailable, try again later")
            }
            client.endConnection()
        }

        override fun onInstallReferrerServiceDisconnected() {}
    })
}
Google keeps the referrer for 90 days and asks apps to call the API only once, on the first run after the install.

Watch the result

Terminal

adb logcat -s InstallReferrer
Run it with the test phone connected over USB before you open the app.

Empty or odd results, and what they mean

No campaign at all after an install from Android Studio
Likely cause: The app wasn’t installed from Google Play
What to do: Install from a testing track through the Play URL
utm_source=google-play&utm_medium=organic
Likely cause: The install didn’t come through your link; this is the usual value for organic installs
What to do: Uninstall, then start from the Play URL on the phone
An old value from an earlier test
Likely cause: The app wasn’t reinstalled, so the first referrer still stands
What to do: Uninstall and install again from the new URL
Only utm_source arrives, the rest is missing
Likely cause: The referrer wasn’t encoded, so & ended it early
What to do: Encode the value: = becomes %3D, & becomes %26
SERVICE_UNAVAILABLE or FEATURE_NOT_SUPPORTED
Likely cause: The Play Store app is updating, missing or too old
What to do: Update the Play Store and try again on the next launch
Nothing on a Huawei phone without Google Play
Likely cause: No Play Store, so no Play referrer
What to do: AppGallery has its own referrer for installs from its store
The organic value is the one Google announced in 2016 and most SDKs still report; treat it as “no campaign”, not as an error.

Where Appy fits

Appy links add a referrer to Google Play by themselves, with the link name, so a test is just a tap on your own link. On Enterprise the Appy SDK reads the referrer on the first launch and credits the install to that link as a verified install. For one-off campaign URLs without Appy, the App Store campaign link builder encodes the referrer for you.

Tools and guides

Sources, read on November 13, 2026

Frequently asked questions

Can I test the install referrer without publishing the app?

Not with a real referrer. Google Play only passes one for installs that come from the Play Store, so the build has to be on a track. The internal testing track is the quickest: up to 100 testers, and new builds are available within minutes.

Why is my install referrer empty?

Most often the app was installed from Android Studio or adb, or it was already installed when you opened the Play URL. Uninstall it, open the Play URL on the phone and install from the Play page.

How long is the install referrer available?

Google keeps it for 90 days, and it doesn’t change unless the app is reinstalled. Read it once, on the first launch, and store what you need.

Does the referrer value need to be URL-encoded?

Yes. Encode the whole value so its = and & stay inside the referrer parameter. Google’s guidance also limits it to 512 characters.

Is the old INSTALL_REFERRER broadcast still a way to test?

No. Use the Play Install Referrer Library, which reads the value from the Play Store app. Tests based on sending the old broadcast with adb don’t reflect what happens on a real install.

Continue exploring

Guide
Oct 21, 2026
8 min read

How to Measure App Installs Without Fingerprinting

Apple doesn’t allow fingerprinting even when users agree to tracking, and EU regulators treat IP-based tracking as access to the device. What still measures installs with proof on iPhone and Android, and a plan that never has to guess.

attribution
fingerprinting
privacy
install attribution
Read article
Guide
Oct 15, 2026
4 min read

How to Decrypt the Meta Install Referrer on Android

Facebook and Instagram can tell your app which campaign, ad set and ad brought an install, views included. How to read it and decrypt it.

meta install referrer
facebook ads
instagram ads
android
Read article
Guide
Aug 14, 2026
11 min read

Deferred Deep Linking Without an SDK: How It Works

You can carry link intent across an app install without embedding an attribution SDK. What actually survives the store boundary on Android and iOS, what breaks, and what each workaround costs in privacy.

deferred deep linking
install referrer
ios
android
Read article

Looking for something else? Browse all topics on the blog.

Let the link carry the referrer

Appy links send Android phones to Google Play with a referrer already attached, and iPhones to the App Store. Free plan, no credit card.