# Android referral quickstart

On Android, the invitation travels inside the Google Play install referrer, so a new person needs no paste step and no code to read it. The SDK reads the referrer at first launch and matches the invitation. This quickstart installs the SDK, claims the install when the person signs up, and receives the webhook that tells your backend to grant the reward.

For the whole path, including the dashboard setup, read the [referrals guide](https://warplink.app/docs/guides/referrals).

## What you need

- An Android app registered in WarpLink with its package name and signing certificate SHA256 fingerprint. [Find your app identifiers](https://warplink.app/docs/guides/find-app-identifiers) shows where each value lives.
- An SDK key from **Keys**, then **SDK keys**. If your organization has several apps, create the key for this app.
- A webhook endpoint, added under **Referral handoff**, then **Webhook**. See [Receive referral webhooks](https://warplink.app/docs/guides/webhooks).

Android needs no handoff switch. The Setup Check id `android_recovery_fingerprint` reports whether the signing fingerprint is on the app.

## Install SDK 1.2.0

```kotlin
dependencies {
    implementation("app.warplink:sdk:1.2.0")
}
```

The SDK reads the invitation through Google's Play Install Referrer library (`com.android.installreferrer:installreferrer`), which it brings in for you. Call `WarpLink.configure` in `Application.onCreate()` with an `onLink` callback, as shown in the [Android SDK setup](https://warplink.app/docs/sdks/android#configure-the-sdk). SDK 1.1.x cannot read an invitation.

## Mark a link as a referral link

Open a link in the dashboard and turn on **Referral link**, or send `is_referral` over REST:

```bash
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, and the id tells you whose invitation earned the credit. [Create referral links](https://warplink.app/docs/guides/referrals#create-referral-links) covers converting existing links in bulk.

## Read the invitation

A friend taps the link on an Android phone without your app and goes to Google Play. Google Play hands the install referrer to the SDK at first launch, the invitation rides inside it, and the SDK matches it. The match is exact: `matchMethod` is `android_referrer`.

The match arrives in `onLink` like any other deferred link, and the SDK keeps the evidence for the claim. You do not write code to read it.

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

An install that does not come from Google Play, such as `adb install` or a direct APK, has no install referrer. [Test referrals](https://warplink.app/docs/guides/referrals/testing) shows how to test through the store path.

### Redeem pasted text

If your onboarding also accepts pasted invitation text, pass it to `redeemInvitation`:

```kotlin
WarpLink.redeemInvitation(pastedText) { result ->
    result.onSuccess { link ->
        if (link != null) showApplied() // null: not an invitation, or no match
    }.onFailure { error ->
        showMessage(error.message) // says how to open the link again
    }
}
```

The SDK never reads the clipboard. Text that is not a WarpLink invitation sends nothing and returns `null`.

## Claim the install

When the friend signs up, call `claimReferral` with 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.

```kotlin
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: claim.flags has "outside_window"
            ReferralClaimStatus.IGNORED -> Unit // already credited: see claim.duplicateOf
            ReferralClaimStatus.NONE -> Unit    // no referral link brought this install
        }
    }.onFailure { error ->
        // Unreachable server, refused key, or an empty or too long installer id.
        Log.w("Referral", error)
    }
}
```

`claimReferral(installerId, callback)` is safe to repeat. The first valid claim for an app and installer id wins, and the same call again returns the same claim.

### Handle each status

| `status` | What to do in the app |
|----------|----------------------|
| `CLAIMED` | Nothing more. The webhook is on its way |
| `FLAGGED` | Nothing more. Your backend decides from the `referral.flagged` event |
| `IGNORED` | Nothing. A reward is never granted twice from our side |
| `NONE` | Carry on. The install did not come from a referral link |

`NONE` is an ordinary answer, not an error. The result also carries `referralId`, `linkId`, `linkUrl`, `matchMethod`, `isExact`, `matchConfidence`, `flags`, `duplicateOf`, `updated` and `replayState`.

For rewards of value, claim from your backend with `POST /v1/referrals/claims` and let your own rules decide when a sign-up has earned one. See [Claim from the SDK or from your backend](https://warplink.app/docs/guides/referrals#claim-from-the-sdk-or-from-your-backend).

## Receive the webhook

Your endpoint receives `referral.claimed` within seconds of the claim. Verify the signature on the raw body, skip an event id you have seen, then grant the reward in your own system:

```js
if (event.type === 'referral.claimed') {
  await grantReward({
    inviterLinkId: event.data.link.id,
    newUserId: event.data.installer_id,
    exact: event.data.match.exact,
  });
}
```

[Receive referral webhooks](https://warplink.app/docs/guides/webhooks) has the signature code for Node.js and Python, and [Reward recipes](https://warplink.app/docs/guides/referrals/rewards) shows how to turn an event into a reward.

## Test it

Install the app from a Google Play internal testing track, because the install referrer exists only on a store install. Tap the link, install, open the app, sign up with a fresh installer id, and claim. [Test referrals](https://warplink.app/docs/guides/referrals/testing) lists the steps and the checks.

## Next

- [Referrals guide](https://warplink.app/docs/guides/referrals) for setup, credit windows and the report
- [Test referrals](https://warplink.app/docs/guides/referrals/testing) and [Reward recipes](https://warplink.app/docs/guides/referrals/rewards)
- [Android attribution](https://warplink.app/docs/sdks/android/attribution) for match types and evidence fields
- [iOS quickstart](https://warplink.app/docs/guides/referrals/ios), [React Native quickstart](https://warplink.app/docs/guides/referrals/react-native), [Flutter quickstart](https://warplink.app/docs/guides/referrals/flutter)