How to Test the Install Referrer and Referral Links

To test the Google Play install referrer, install your app from a Google Play internal testing track after tapping a link that opens your store listing with a referrer value. Then read the first-launch result in Logcat and claim the install. A cable install never exercises the referrer, because the Play Store app is the only thing that stores it.

This guide covers the whole referral test: Android through the store, iPhone through the paste step, the signed webhook without any phone, and the three places to read the result. It uses WarpLink SDK 1.2.0. The reference version of these steps lives in Test referrals.

Before you test

1. Update the app to SDK 1.2.0 or later. Builds on 1.1.x cannot read an invitation.
2. Open the app in the dashboard, go to Referral handoff, and choose Setup. Fix anything the checks list.
3. Create a referral link, or turn on Referral link for an existing one. A tap from before the link became a referral link is not a referral.
4. Add a webhook endpoint under Referral handoff, then Webhook.

Use a fresh installer id for every run. The first valid claim per app and installer id wins, so reusing an id answers ignored on the second run.

Test the webhook without a phone

This is the fastest test, so run it first. Send test on the webhook tab sends one signed webhook.test event to the saved address and shows what your server answered. The event has the same shape and headers as a real one, with an id that starts evt_test_. We send it once and never retry it.

curl -X POST https://api.warplink.app/v1/webhook-endpoints/ENDPOINT_ID/test \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"

The MCP tool send_test_webhook does the same. A passing test proves your address, your signature check, and your reply. It does not prove the link or the SDK, so move on to a phone. Receive a referral reward webhook in Node.js shows the receiver.

Test the Android install referrer

Google's Play Install Referrer Library reads a value that Google Play stores with the install. Two facts shape every test:

• The value exists only when Google Play performs the install. An install by adb install or a direct APK has none.
• Google's guidance is to call the API once, on the first execution after install, because the value does not change unless the app is reinstalled.

Install from an internal testing track

1. Upload a build to a Google Play internal testing track and add your test phone's Google account as a tester.
2. Delete the app from the phone before each run.
3. Open the referral link on the phone. It sends the phone to Google Play with the invitation inside the install referrer.
4. Install from the store listing, then open the app.
5. Sign up as a new test user with a fresh installer id, and call claimReferral.

The match is exact: matchMethod is android_referrer. Register the signing certificate SHA256 fingerprint on the app first. For a build from a Play track, use the fingerprint of the key that signed that build. Find your app identifiers shows where to find it.

Read the first launch in Logcat

Turn on debug logging, then follow the WarpLink tag while the app launches:

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

adb logcat -s WarpLink

The SDK logs one line about the referrer. Install referrer matched link ... is the line to expect from a WarpLink referral link: the read worked and found your link. Install referrer carried a recovery token means the invitation rode in the referrer as a per-tap token. Install referrer carried no WarpLink link id means the referrer was present but did not come from a WarpLink link, which is what an organic install looks like. A line that says the referrer is unavailable names the cause.

Open your listing with a referrer by hand

To see that Google Play keeps a referrer through an install, open your listing from the computer with a hand-built URL:

adb shell am start -a android.intent.action.VIEW \
  -d "https://play.google.com/store/apps/details?id=com.example.app\&referrer=utm_source%3Dtest"

Install from that page and read the raw referrer string with Google's library, as in Android install referrer referral code in Kotlin. This checks the Google Play side. It cannot stand in for a WarpLink referral link, which writes the link id and a per-tap token that only our redirect knows, so finish with a real tap.

A broadcast such as adb shell am broadcast -a com.android.vending.INSTALL_REFERRER does not write the value Google's library returns. The library asks the Play Store app for it through an AIDL interface, so use the store path above.

Test on an iPhone

iPhone has no install referrer. The invitation travels with the person instead, and a paste step in your app hands it to the SDK. Run it from a build that went through the store path, such as TestFlight.

1. Delete the app from the phone, so the tap counts as a first install.
2. Open the referral link on the phone. You see the invitation page, then the App Store or a TestFlight build.
3. Install and open the app. Tap the paste button on your first screen. The system paste button pastes in one tap with no permission prompt.
4. Check that redeemInvitation returned a link. A nil result means nothing was confirmed.
5. Sign up as a new test user with a fresh installer id, and call claimReferral.

An invitation pasted on an iPhone is an exact match: matchMethod is install_token and isExact is true. React Native and Flutter apps paste into a field of their own: copy the invitation text from the invitation page and paste it there. The full code is in Make a referral link survive the App Store on iPhone.

Read the result

In the app. claimReferral returns a result with a status. claimed means the install is credited.

In the Referrals report. Open Referral handoff, then Referrals. Each row shows the link, the installer id, the match, and the webhook result. Open a row to see the claims, the events we sent with their payloads, and every delivery attempt.

Over the API. GET /v1/referrals returns the same list, newest first. Filter it to your test user:

curl "https://api.warplink.app/v1/referrals?installer_id=TEST_INSTALLER_ID&status=delivered" \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"

The filters are installer_id, link_id, status, match, platform, app_id, from and to. The key needs referrals:read. The status tells you how far the referral got: claimed is recorded, delivered means your endpoint answered 2xx, retrying has another attempt scheduled, failed used every attempt, flagged was claimed after the credit window, and duplicate was a later claim for an installer that already held a credit.

Run the test again

Delete the app from the phone and install it again, because the install referrer belongs to the install. Use a fresh installer id, or delete the test referral with DELETE /v1/referrals/{id} to reuse one.

Common failures

The claim answers none and you expected a credit. Check the link first: it must be a referral link, and the tap must be after referral_since. Then check the credit window you chose, and whether the phone already had the app. That counts only when Count people who already have the app is on.

Logcat says the referrer carried no WarpLink link id. The install did not follow a tap on a WarpLink referral link. Tap the link on the phone, then install.

Nothing logs at all. Confirm debugLogging is on, the app is on SDK 1.2.0, and the app was deleted before the install so this is a first launch.

No webhook arrives. Open the referral in the report and read its delivery attempts. A 5xx answer or a timeout triggers a retry, up to 5 attempts over 20 minutes. A 4xx or 3xx answer ends the event as failed. Fix the endpoint, then choose Resend.

Frequently Asked Questions

How do I test the Google Play install referrer before release?

Install the app from a Google Play internal testing track after tapping a link that sends the phone to your listing with a referrer value. The referrer exists only for installs that Google Play performs, so a cable install of a debug build does not exercise it.

Can I test the install referrer with adb?

You can use adb to open your Play listing with a referrer parameter and to read Logcat output. You cannot write a referrer with a broadcast, because Google's library asks the Play Store app for the value instead of listening for a message.

Why does the install referrer come back empty on my second test?

Google documents that the value does not change unless the app is reinstalled, and the SDK reads it once on first launch. Delete the app and install it again from the store to repeat a test.

How do I test a referral link on an iPhone?

Delete the app, open the referral link on the phone, install from TestFlight or the App Store, open the app, and tap the paste button. Then claim with a fresh installer id and check the Referrals report.

How do I test the referral webhook without a phone?

Send a test event from the webhook tab, or call the test endpoint over REST. It sends one signed webhook.test event with an id that starts evt_test_. It proves your address, signature check, and reply.

Related Guides

• Reference: Test referrals and the referrals guide.
• Android code: Android install referrer referral code in Kotlin.
• Other platforms: React Native referral program and Flutter referral system.
• Launch pass: A referral link checklist for launch.
• General deep link testing: How to test deep links.

How WarpLink Helps

A referral test has three parts that normally sit in different places: the link, the install, and the result. We keep them in one record. The Referrals report shows the match, the claims, and every webhook delivery for your test user, and the same data comes back over REST and MCP.

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.