WarpLink SDK 1.2.0: Referral Links That Survive the Install

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

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.

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

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 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 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 covers link, install, claim, webhook, and report.
• What changed: The changelog lists every 1.2.0 addition.
• The install side on iOS: Deferred Deep Linking on iOS walks through the match cascade in Swift.
• Use case: App referral programs shows the invite flow end to end.