# WarpLink SDK 1.2.0: Referral Links That Survive the Install

> WarpLink SDK 1.2.0 for iOS, Android, React Native, and Flutter: invite links that keep their code through the install, claimReferral, and a signed webhook.

_Last updated: 2026-10-26_

> **TL;DR:** WarpLink SDK 1.2.0 is available today for iOS, Android, React Native, and Flutter. An invite link now carries its referral code through the App Store or Google Play install, the app confirms the invitation on first launch, and your backend grants the reward from a signed `referral.claimed` webhook. The [referrals guide](https://warplink.app/docs/guides/referrals) walks the whole path.

WarpLink is link infrastructure for mobile teams: deep linking, install attribution, and real-time analytics in one SDK. Version 1.2.0 ships for all four SDKs on the same day and adds referral links to every one of them.

## How a Referral Works

A referral link is an invitation one of your users shares with a friend. The friend taps it, installs, opens the app, and signs up. We credit the install to the link, and your backend receives a signed webhook.

1. **Create a referral link.** Turn on **Referral link** in the dashboard, or send `is_referral` over REST or MCP.
2. **The friend taps it.** With **Offer referral handoff on iOS** turned on for the app, an iPhone visitor without your app sees a short invitation page, then the App Store. An Android visitor goes to Google Play with the invitation inside the install referrer.
3. **The app opens for the first time.** The SDK picks up the invitation, as described below.
4. **The friend signs up.** Your app calls `claimReferral` with your own id for the new user.
5. **Your backend gets `referral.claimed`** and grants the reward.

## The Paste Control on iPhone

An App Store install carries no data, so on iPhone the first launch asks for the invitation. `WarpLinkPasteButton` (SwiftUI, iOS 16 and later) and `WarpLinkUIPasteButton` (UIKit) show the system paste control. The person taps it, the SDK confirms the invitation, and the match is exact.

```swift
WarpLinkPasteButton { result in
    switch result {
    case .success(let link):
        // nil means nothing was confirmed.
        if link != nil { showInvitationApplied() }
    case .failure(let error):
        showMessage(error.localizedDescription)
    }
}
```

The SDK never reads the clipboard itself. iOS asks the person to allow each paste, and the SDK sees only the text the control hands over. The step is an offer, not a gate: a person can skip it and onboarding continues. React Native and Flutter call `redeemInvitation(text)` with the text from a field on your onboarding screen.

## The Play Install Referrer on Android

On Android there is nothing to paste. The SDK reads the `wl_rt` value from the Play install referrer on first launch, the invitation rides inside it, and the match is exact. No code change is needed.

## claimReferral After Sign-Up

When the friend signs up, tell WarpLink which of your users they are. Call `claimReferral` with an installer id, a random id you store with the new user.

```kotlin
WarpLink.claimReferral(user.warplinkId) { result ->
    result.onSuccess { claim ->
        // CLAIMED or FLAGGED: recorded. Your webhook grants the reward.
        // IGNORED: already credited. NONE: no referral link brought this install.
    }
}
```

The first valid claim for an app and installer id wins, and sending the same claim again is safe. A `none` result is an ordinary answer, not an error.

## The Claim API and Signed Webhooks

For rewards of value, claim from your backend. Call `POST /v1/referrals/claims` with an API key that has the `referrals:write` scope and an `Idempotency-Key` header. Pass the `attributionId` from the SDK's attribution result as `install_id`.

A claim that credits a new referral sends a signed webhook: `referral.claimed`, or `referral.flagged` when the claim arrives after the credit window. `referral.updated` follows when an exact claim replaces an estimate. A claim with the result `none` and a repeat claim send no webhook. [Receive referral webhooks](https://warplink.app/docs/guides/webhooks) has the payloads, signature code for Node.js and Python, retries, and resends. WarpLink does the matching and keeps the record. Your system grants the reward.

## Exact and Estimated, Reported on Every Match

Every referral records how it was matched, in `match.method`:

| Match | `match.method` | Exact |
|-------|----------------|-------|
| Invitation pasted on iPhone | `install_token` | Yes |
| Play install referrer on Android | `android_referrer` | Yes |
| Tap on a device that already had the app | `link_open` | Yes |
| Device signals on iPhone | `probabilistic` | No, with a `confidence` |

Use `exact` and `evidence_class` to decide how a referral counts in your own rules. The `matchGuaranteed` flag from SDK 1.1.0 is unchanged.

## The Referrals Report

Every referral appears in the **Referrals** report in the dashboard and in each app's **Referral handoff** tab: the link, the installer id, the match, and the webhook result. A claim with the result `none` records nothing. The same list is `GET /v1/referrals` and the MCP tool `list_referrals`, and a CSV export is available. The MCP server also gains `get_referral_page` and `update_referral_page` for the invitation page, `get_referral`, `claim_referral`, and `delete_referral` for the records, tools for webhook endpoints, and `create_link`, `update_link`, and `list_links` take `is_referral`.

## Smaller Additions

- **Evidence fields.** `WarpLinkDeepLink` and `AttributionResult` gain `attributionId`, `matchMethod`, `evidenceClass`, `replayState`, `capturedParams`, and `tappedAt`.
- **New scopes.** API keys and MCP connections can hold `referrals:read` and `referrals:write`.
- **Pins move to 1.2.0.** The Flutter SDK pins the iOS and Android SDKs at 1.2.0, and the React Native SDK bridges to the same 1.2.0 native SDKs.

## How to Upgrade

Change the SDK version to 1.2.0 in Swift Package Manager, Gradle, npm, or pub, and rebuild. Builds on 1.1.x keep working for links and installs, but they cannot read an invitation. The [upgrade guide](https://warplink.app/docs/changelog#upgrading) has the exact dependency line for each platform.

To turn referrals on, open the app in the dashboard, go to **Referral handoff**, and choose **Setup**. The checks show what each platform still needs. The [data flow page](https://warplink.app/docs/trust/data-flow) lists the fields each SDK sends on a claim.

## Frequently Asked Questions

**Does the WarpLink SDK read the clipboard?**
No. On iPhone the SDK shows the system paste control and the person taps it. The SDK sees only the text that control hands over, and iOS asks the person to allow each paste.

**Is a referral match on iPhone exact?**
Yes, when the person completes the paste step. The invitation they paste carries an install token, so the match is exact. Without the paste step, an iPhone referral can still be credited as an estimated match from device signals, and a later exact claim from the same person upgrades it.

**What do I need to change on Android?**
Nothing in code. The SDK reads the `wl_rt` value from the Play install referrer on first launch, so the invitation arrives as an exact match. Register the app's signing certificate so the setup check can confirm the path.

**Who grants the reward?**
Your backend does. WarpLink records the referral and sends a signed `referral.claimed` webhook. The reward, the rules around it, and the money stay in your own system.

## Related Guides

- **The full path:** [Referrals](https://warplink.app/docs/guides/referrals) covers link, install, claim, webhook, and report.
- **What changed:** The [changelog](https://warplink.app/docs/changelog) lists every 1.2.0 addition.
- **The install side on iOS:** [Deferred Deep Linking on iOS](https://warplink.app/blog/deferred-deep-linking-ios) walks through the match cascade in Swift.
- **Use case:** [App referral programs](https://warplink.app/use-cases/app-referral-programs) shows the invite flow end to end.