Android Install Referrer Referral Code in Kotlin

A referral code survives a Google Play install when it rides in the referrer parameter of the Play Store link. Google Play keeps that string through the install and returns it to your app on first launch through the Play Install Referrer API. Your app reads it once, parses the code, and credits the inviter.

This guide shows the plain Kotlin version first, so you see exactly what Google gives you. Then it shows what the WarpLink Android SDK does with the same signal, and how claimReferral turns it into a credited, exact referral. It uses SDK 1.2.0.

How the code travels through the Play Store

A friend taps an invite link on an Android phone that does not have your app. They land on your Google Play listing, tap Install, and open the app. Nothing in that path carries your app's query string. The one channel that does is the referrer parameter on the Play Store URL:

https://play.google.com/store/apps/details?id=com.example.app&referrer=ref%3DANA123

The value must be URL-encoded, so ref=ANA123 becomes ref%3DANA123. Google Play stores it with the install, and the app can ask for it on first launch. The Play Store app, not the phone's browser or a clipboard, is the carrier. That is why Android needs no paste step.

Read the referrer in Kotlin

Add Google's library to the app module. This is the version Google documents at developer.android.com:

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

Then connect, read, and close. The call is asynchronous, so everything happens inside onInstallReferrerSetupFinished:

import android.content.Context
import android.net.Uri
import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerStateListener

fun readReferralCode(context: Context, onResult: (code: String?, readable: Boolean) -> Unit) {
    val client = InstallReferrerClient.newBuilder(context).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(responseCode: Int) {
            if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
                val referrer = client.installReferrer.installReferrer
                onResult(Uri.parse("?$referrer").getQueryParameter("ref"), true)
            } else {
                // SERVICE_UNAVAILABLE is worth a retry on a later launch.
                val unavailable =
                    responseCode == InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE
                onResult(null, !unavailable)
            }
            client.endConnection()
        }

        override fun onInstallReferrerServiceDisconnected() {
            // Retry on the next request to Google Play.
        }
    })
}

client.installReferrer returns a ReferrerDetails object. Its installReferrer property is the string you put in the link, for example ref=ANA123. It also carries referrerClickTimestampSeconds and installBeginTimestampSeconds.

Read it only once

Google's guidance is to call the API only once, during the first execution after install, because the value does not change unless the app is reinstalled. Keep a flag in SharedPreferences and skip the connection when it is set. Set the flag once Google Play answers, and leave it unset when the service is unavailable so the next launch tries again:

val prefs = context.getSharedPreferences("referral", Context.MODE_PRIVATE)
if (!prefs.getBoolean("referrer_read", false)) {
    readReferralCode(context) { code, readable ->
        if (readable) prefs.edit().putBoolean("referrer_read", true).apply()
        if (code != null) pendingReferralCode = code
    }
}

Hold the code until the person signs up, then send it with the new account to your backend. That is a complete referral on Android with no third-party code. What it does not give you is a record of the tap, a check that the code belongs to a live invite, a duplicate guard, or a report.

What the WarpLink SDK does with the same signal

With WarpLink, the referral link is the thing that puts the code in the referrer, and the SDK reads it for you. A WarpLink referral link redirects to Google Play with the link id and a per-tap token inside the install referrer. On first launch, SDK 1.2.0 reads it through the same Google library, which the SDK brings in as a dependency, and matches it to the tap.

Three steps replace the code above.

1. Create a referral link. Any link that belongs to an app can be a referral link. Turn on Referral link in the dashboard, or send is_referral over REST:

curl -X POST https://api.warplink.app/v1/links \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "slug": "invite-ana",
    "destination_url": "https://example.com/invite",
    "is_referral": true
  }'

Store the returned link id with the user who shares it. The webhook names that link later, and the id tells you whose invitation earned the credit.

2. Configure the SDK. Register the signing certificate SHA256 fingerprint on the app in the dashboard, then configure once in Application.onCreate():

WarpLink.configure(
    context = this,
    apiKey = "wl_live_yoursdkkeyhere000000000000000000",
    options = WarpLinkOptions(onLink = { result ->
        result.onSuccess { deepLink ->
            if (deepLink.isDeferred) showWelcomeFromInvitation(deepLink)
        }
    })
)

The referrer read happens at first launch with no code of yours. The match arrives in onLink like any other deferred link, and the SDK keeps the evidence for the claim.

3. Claim the install when the person signs up. Pass an installer id: a dedicated random id for the new user, 1 to 128 characters. Do not use a primary key, an email address, or a phone number.

import android.util.Log
import app.warplink.WarpLink
import app.warplink.referral.ReferralClaimStatus

WarpLink.claimReferral(user.warplinkId) { result ->
    result.onSuccess { claim ->
        when (claim.status) {
            ReferralClaimStatus.CLAIMED -> Unit // credited inside the window
            ReferralClaimStatus.FLAGGED -> Unit // credited after the window
            ReferralClaimStatus.IGNORED -> Unit // already credited: see claim.duplicateOf
            ReferralClaimStatus.NONE -> Unit    // no referral link brought this install
        }
    }.onFailure { error ->
        Log.w("Referral", error)
    }
}

claimReferral(installerId, callback) is safe to repeat. The first valid claim for an app and installer id wins.

What the claim records

A referral read from the Play install referrer is an exact match: matchMethod is android_referrer and isExact is true. The tap time, the install time, the link, and the installer id are stored with the referral. Your backend receives a signed referral.claimed webhook, grants the reward from its own rules, and the credited install shows in the Referrals report next to the rest of your link analytics.

Exact versus estimated referral matches defines every evidence field. Verify a referral before you grant the reward shows what to check on the server.

Common problems

The read returns nothing on a debug build. The install referrer exists only when Google Play installs the app. An install by adb install or a direct APK has none. Install from a Google Play internal testing track, as How to test the install referrer and referral links shows.

The second launch returns nothing, or a repeat test finds the old value. The value is tied to the install. Delete the app and install it again for a fresh run.

The code is empty after parsing. The referrer value was not URL-encoded, or the parameter name differs from the one you read. Log the raw installReferrer string and compare.

claimReferral answers NONE. No referral link brought this install. Check that the link is a referral link and that the tap was after referral_since.

Frequently Asked Questions

How do I pass a referral code through a Google Play install?

Add the code to the referrer parameter of the Play Store link, for example &referrer=ref%3DANA123. Google Play keeps the value through the install. On first launch, the Play Install Referrer library returns it as a string your app parses.

Is the Play install referrer reliable enough for rewards?

It is a strong signal because Google Play delivers it through the install, not the clipboard or the browser. It exists only for installs from Google Play, and your app reads it once. For a reward, claim the install on your server and treat it as one input next to your own rules.

How many times can I read the install referrer?

Google says to call the API only once, on the first execution after install, because the value does not change unless the app is reinstalled. Store a flag after the first read and skip the call on later launches.

Does the WarpLink SDK read the install referrer for me?

Yes. SDK 1.2.0 reads the referrer on first launch through Google's library, which it brings in for you. The match arrives with the method android_referrer and exact set to true, and you call claimReferral after sign-up to credit the inviter.

Do Android referrals need a paste step like iPhone?

No. Google Play carries the invitation inside the install referrer, so the new person sees no extra screen.

Related Guides

• Quickstart: Android referral quickstart and the full referrals guide.
• Code or link: Referral code vs referral link shows how to combine a code with a link that survives the install.
• Test it: How to test the install referrer and referral links.
• Other platforms: React Native referral program, Flutter referral system, and referral links on iPhone.
• The general mechanism: Deferred deep linking on Android.
• The rules: App Store and Google Play referral reward rules.

How WarpLink Helps

The plain Kotlin version reads a string. The parts around it are what make a referral usable: the link that writes the code into the install, the record that joins a tap to a first launch, the duplicate guard, and the signed event your backend can trust. That is our job. You create a referral link, configure the SDK, and call claimReferral after sign-up. The reward and its rules stay in your system.

One workflow, three pillars. Deep linking carries the invitation, install attribution credits the link that produced the new user, and real-time analytics shows referrals beside every other link. Sub-10ms redirects on the way in, one SDK on the way out.

Create a free WarpLink account and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.