Guide
The Play referrer has two readers, and they answer different questions
One parameter on a Play Store URL, two entirely separate systems reading it. One is a console report you can have this afternoon with nothing added to your app; the other is an interface your app calls at first launch. Teams reach for the second when they wanted the first, and pay for an integration that answers a question they were not asking.
What does the Play referrer parameter carry?
A Play Store listing URL accepts a referrer parameter, and inside it you nest ordinary UTM fields:
https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dinstagram%26utm_medium%3Dbio%26utm_campaign%3DlaunchThe payload is a query string inside a query string, which is why it has to be URL-encoded — the inner & and = belong to the referrer value, not to the store URL.
What happens next depends entirely on who is reading, and the two readers have almost nothing in common.
| Play Console acquisition report | Play Install Referrer API | |
|---|---|---|
| Where you read it | Play Console, in a browser | Inside your app, at first launch |
| Code required | None | Client library or the AIDL interface |
| Granularity | Aggregate, by campaign | Per install |
| Answers | How many did this campaign bring | Where did this install come from |
| Available when | After store-listing visits accumulate | First launch after install |
Both are legitimate. They are not alternatives to each other, and the decision between them is not about effort — it is about which question you have.
Do you need an SDK to see UTM campaigns in Play Console?
Play Console’s acquisition report breaks store-listing traffic down by dimension, and one of those dimensions is tracked channels (UTM) — unique users who reached your listing from a UTM-tagged link. You can filter by UTM source and campaign alongside country, language, store listing and install state.
Nothing goes into your app for this. The tagging happens on the link, Google Play attributes the listing visit when the visitor arrives, and the report is there when you open the console.
Two boundaries are worth knowing before you rely on it. The report covers store-listing acquisition specifically — it does not include visitors arriving through other surfaces on Google Play, such as editorial placements, and it does not cover installs recorded through mechanisms like backup-and-restore. And it is aggregate by design: you learn that a campaign produced installs, not which install came from which tap.
For most people asking “which of my links is working”, this is the entire answer, and it is available today.
What does the Install Referrer API return?
The Play Install Referrer API is an AIDL interface exposed by the Play Store app. Your app calls it after installation and receives:
- the referrer URL — the string that was attached to the click
- the referrer click timestamp, client-side and server-side
- the installation begin timestamp, client-side and server-side
- the app version at first install
- whether the user interacted with your instant experience in the past 7 days
Google requires Play Store version 8.3.73 or later, and offers a client library for Kotlin and Java or the raw AIDL interface for everything else.
This is genuinely per-install, which is what makes it the foundation most Android attribution is built on — and it is also why every mobile measurement platform integrates it rather than expecting you to. If you are calling it directly, you are building the thing they sell.
The question it answers well is which campaign produced this particular user. If you do not need to join an install to a user record, you are paying an integration cost for precision you will aggregate away anyway.
Which of the two readers do you need?
The decision collapses to one question: does anything downstream need to know which install this is?
- Reporting on channels and campaigns — how the bio link compares to the newsletter, whether last week’s partner post did anything — is aggregate. Play Console, no code.
- Anything joined to a user record — a referral credit, an invite that has to unlock something, a partner paid per install — is per-install. Install Referrer API, or a measurement platform that wraps it.
Teams reach for the second by default because it sounds more rigorous. It is more precise, and precision you discard on the way to a bar chart is a cost with no return.
Does the Play referrer work on iOS?
The App Store does not read the referrer parameter at all. iOS carries campaign context in a different shape entirely — ct and pt on the product URL, read in App Store Connect Analytics rather than by your app — and there is no iOS equivalent of the Install Referrer API whatsoever.
That has a practical consequence for anyone publishing one address to a mixed audience, which is nearly everyone. A link carrying only a UTM payload is tagged on Android and untagged on iOS. A link carrying only ct and pt is the reverse. Neither store reads the other’s parameters, and neither warns you.
An AppIn link composes both from the campaign you set on it: Apple’s ct alongside your pt, and the Play referrer carrying utm_source and utm_campaign, on every click. The mechanics of what gets composed covers the fields themselves. Nothing goes into your app on either platform — which also means neither store’s per-install path is available, and if that is what you need, the boundary is worth reading before you build around it.
One more thing that catches Android campaigns specifically, and the console cannot show it: a tagged link opened inside TikTok’s or Instagram’s in-app browser can fail the hand-off to Play before the listing is ever reached. It happens on Android too, not only on iOS, and it reports as a campaign nobody clicked.
Questions
- What does the referrer parameter on a Play Store URL carry?
- A URL-encoded string of UTM fields — typically utm_source, utm_medium and utm_campaign. It rides on the store URL as referrer=... and Google Play reads it when the visitor arrives at the listing.
- Do I need an SDK to see UTM campaigns in Play Console?
- No. Play Console's acquisition report breaks store-listing traffic down by UTM source and campaign under tracked channels, without anything added to your app. The SDK is only needed for the Install Referrer API, which is a different reader.
- What is the difference between Play Console UTM reporting and the Install Referrer API?
- Play Console reports aggregate store-listing acquisition by campaign and needs no code. The Install Referrer API is called from inside your app at first launch and returns the referrer string plus click and install timestamps for that specific install.
- Does the Play referrer work on iOS?
- No. The App Store does not read it. iOS uses campaign links with ct and pt parameters instead, and a link carrying only a referrer string is untagged on iOS.
- Does the referrer value need to be URL-encoded?
- Yes. The UTM payload is nested inside the referrer parameter, so its own separators have to be encoded or the store URL is parsed wrongly.
Facts on this page were last checked on . Competitor pricing and platform behaviour both move; check theirs before deciding.
Keep reading
- GuideYour campaign is missing from App Store Connect. Here is the order to check.A campaign link that drove installs can report nothing in App Store Connect. Three thresholds Apple publishes explain most empty rows — check them first.
- GuideSearching for page.link will miss most of your dead Dynamic LinksThe shutdown took custom domains too, not just page.link. Where the dead links actually hide, what to grep for, and which ones you can never fix.
- GuideiOS has no install referrer. It has three other things.Android has one Install Referrer API. iOS has no equivalent — it has three separate systems, and picking the wrong one is why campaign data goes missing.
One link, both stores tagged
AppIn composes the Play referrer and Apple's ct on the same link, from the campaign you set. Nothing goes into your app.
See plans