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.
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
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
https://play.google.com/store/apps/details
Store page
The standard Google Play address for an app.
?id=com.example.myshop
Package
Your application ID, exactly as in the Play Console.
&referrer=
Referrer parameter
Everything after it is handed to your app after the install.
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.
Test it end to end
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.
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.
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.
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.
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.
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.
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() {}
})
}Watch the result
Terminal
adb logcat -s InstallReferrerEmpty or odd results, and what they mean
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
- App Store and Google Play campaign link builderAdds campaign tokens to App Store links and an encoded referrer to Google Play links.
- What is the install referrer?The short definition, and what it can and can’t tell you.
- UTM parameters for app campaignsHow UTMs survive the store on Android, and why they don’t on iPhone.
- Appy Android SDKReads the referrer on the first launch and credits the install to the link.
Sources, read on November 13, 2026
- Android Developers · Play Install Referrer Librarydeveloper.android.com/google/play/installreferrer/library
- Android Developers · ReferrerDetails referencedeveloper.android.com/reference/com/android/installreferrer/api/ReferrerDetails
- Play Console Help · Set up an open, closed or internal testsupport.google.com/googleplay/android-developer/answer/9845334
- Android Developers · Referrer format for Google Play URLs (Play Games on PC)developer.android.com/games/playgames/user-acquisition
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
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.
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.
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.
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.