# How to Test the Install Referrer and Referral Links

> Test the Google Play install referrer and referral links before release: Play internal testing, adb checks, the iPhone paste path, and the test webhook.

_Last updated: 2026-10-26_

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](https://warplink.app/docs/guides/referrals/testing).

## 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.

```bash
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](https://warplink.app/blog/referral-reward-webhook-node) shows the receiver.

## Test the Android install referrer

Google's [Play Install Referrer Library](https://developer.android.com/google/play/installreferrer/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](https://warplink.app/docs/guides/find-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:

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

```bash
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:

```bash
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](https://warplink.app/blog/android-install-referrer-referral-code). 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](https://warplink.app/blog/ios-referral-link-after-install).

## 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:

```bash
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](https://warplink.app/docs/guides/referrals/testing) and the [referrals guide](https://warplink.app/docs/guides/referrals).
- **Android code:** [Android install referrer referral code in Kotlin](https://warplink.app/blog/android-install-referrer-referral-code).
- **Other platforms:** [React Native referral program](https://warplink.app/blog/react-native-referral-program) and [Flutter referral system](https://warplink.app/blog/flutter-referral-system).
- **Launch pass:** [A referral link checklist for launch](https://warplink.app/blog/referral-link-checklist-for-launch).
- **General deep link testing:** [How to test deep links](https://warplink.app/blog/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](https://dash.warplink.app/auth/signup) and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.