# Make a Referral Link Survive the App Store on iPhone > How a referral code survives the App Store install on iPhone: the invitation page, the system paste button, and claimReferral, with SwiftUI code. _Last updated: 2026-10-26_ A referral link survives the App Store install on iPhone when the invitation travels with the person instead of the install. A short invitation page copies the code, the person installs, and a system paste button in your app hands the code to the SDK. The match is exact, and `claimReferral` credits the inviter. This guide is the full iPhone path in the order it happens: the tap, the invitation page, the install, the paste button, the claim, and the check that it worked. It uses WarpLink SDK 1.2.0 and the same link, install attribution, and analytics you already use for every other link. ## Why the code disappears at the App Store A person taps `https://acme.aplnk.to/invite-ana` in a message. They do not have your app, so the link goes to the App Store listing. They tap Get, wait, and open the app. At that point your app knows nothing about the tap. The App Store does not hand the URL, or any part of it, to the app it installs. A referral code in a query string, a path, or a custom scheme is gone before the first launch. The same gap runs through every step: the browser, the store, and the app are three separate screens with no shared memory. Link services fill this gap with deferred deep linking, which matches the first launch back to the click from device signals. That works for destinations. For a referral that earns a reward, you want something stronger than an estimate: proof that the person who installed is the person who tapped. On iPhone that proof is a value the person carries across the install themselves. ## The path in five steps 1. **Create the referral link.** Any link that belongs to an app can be a referral link. Turn on **Referral link** in the dashboard, or send `is_referral` over REST. 2. **The friend taps it.** On iPhone without your app, they see a short invitation page. The page copies an invitation to the clipboard and sends them to the App Store. 3. **The friend installs and opens the app.** Your first screen shows the paste button. 4. **The friend taps paste.** iOS asks them to allow it. The SDK reads only the text the button hands over and matches the invitation. 5. **The friend signs up and you claim.** Your app calls `claimReferral` with your own id for the new user, and your backend receives a signed `referral.claimed` webhook. Each step has one job, and the invitation page and the paste button are the two pieces that make the install survivable. ## Step 1: Create the referral link Create the link when a user asks to invite someone, and store the link id with that user. When the webhook arrives, `link.id` tells you whose invitation earned the credit. ```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 }' ``` A link with no app cannot be a referral link and the request answers `400 VALIDATION_ERROR`. The link returns `is_referral` and `referral_since`. A tap before that time does not count as a referral. ## Step 2: Turn on the iOS handoff Open the app in the dashboard, go to **Referral handoff**, and choose **Setup**. The checks list what iOS still needs: an App Store URL on the app, and an iOS build on SDK 1.2.0 or later that we have seen in the last 30 days. Turn on **Offer referral handoff on iOS** when both are green. The switch also works before we detect an SDK 1.2.0 build, and the dashboard then shows a warning: until such a build ships, new iPhone installs from referral links cannot read the invitation and are not credited. This is also where you set the **Referral credit window**: 24 hours, 7 days (the default), or 30 days from the tap. A claim inside the window is credited. A later claim is recorded and flagged so you can decide. Under **Page** you set the look and wording of the invitation page. It shows only for referral links, on an iPhone without your app. Ordinary links never show it. ## Step 3: Add the paste button to your first screen Put the button on the screen where a new person first sees your app. In SwiftUI, `WarpLinkPasteButton` wraps the system paste control (iOS 16 and later): ```swift import SwiftUI import WarpLink struct WelcomeView: View { @State private var message: String? var body: some View { VStack(spacing: 16) { Text("Did a friend invite you?") WarpLinkPasteButton { result in switch result { case .success(let link): // nil means nothing was confirmed. if link != nil { message = "Invitation applied." } case .failure(let error): // The message says how to open the invitation again. message = error.localizedDescription } } if let message { Text(message) } Button("Skip") { continueOnboarding() } } } } ``` UIKit apps use `WarpLinkUIPasteButton` with the same result handling. React Native and Flutter take the pasted text from a field you provide and call `WarpLink.redeemInvitation(text)`. Three details matter here: - **The SDK never reads the clipboard on its own.** The system paste button asks the person to allow each paste, and the SDK sees only the text that button hands over. - **The paste step is an offer, not a gate.** A person can skip it, and onboarding continues. Show a referral as applied only when the result carries a link. Without one, nothing is confirmed, so do not tell the person a referral was applied. - **An expired or changed invitation is refused with `400`.** The error message tells the person to open the invitation link again or ask the friend for a new one. Show it as it is. ## Step 4: Claim after sign-up After the friend signs up, tell WarpLink which of your users they are. You send an installer id: your own random id for the new user, such as a UUID stored in its own column. It is opaque, up to 128 characters, and not an email address, a phone number, or any other personal data. ```swift WarpLink.claimReferral(installerId: user.warplinkId) { result in guard case .success(let claim) = result else { return } switch claim.status { case .claimed, .flagged: break // recorded. Your webhook grants the reward. case .ignored: break // already credited: see claim.duplicateOf case .none: break // 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: no referral link brought this install, and nothing is recorded. For rewards of value, claim from your backend instead. Send your server the `attributionId` from the SDK's attribution result with the installer id, then call `POST /v1/referrals/claims` with an API key that has `referrals:write` and an `Idempotency-Key` header. Your backend holds your rules, so it decides when a sign-up has earned a reward. ## Step 5: Test on a real phone 1. Create a referral link and turn on the app's handoff. 2. Delete the app from the phone so the tap counts as a first install. 3. Open the link on the phone. You see the invitation page, then the App Store or a TestFlight build. 4. Install, open the app, and tap the paste button. 5. Sign up as a new test user with a new installer id, and claim. 6. Open **Referral handoff**, then **Referrals**, and confirm the new row and your webhook delivery. Use a fresh installer id for every run, because the first valid claim per app and installer id wins. Delete a test referral with `DELETE /v1/referrals/{id}` to start over. ## What the claim records Each referral stores how it matched. A pasted invitation records `match.method` as `install_token` with `exact` set to true. The webhook event carries the link, the installer id, the platform, the tap, install, and claim times, and `claimed_via`, which is `sdk` or `api`. The next guide in this series, [exact versus estimated referral matches](https://warplink.app/blog/referral-attribution-exact-vs-estimated), defines every evidence field. ## Common problems **The claim answers `none` and you expected a credit.** Check that the link is a referral link and that the tap came after `referral_since`. Then check the credit window, and whether the person already had the app. A tap on a device that already has the app counts only when **Count people who already have the app** is on. **The iOS switch will not turn on.** Setup lists what is missing. Add the App Store URL, or ship a build on SDK 1.2.0 and open it once so we see it. **The paste returns no link.** The clipboard may hold something else by the time the person pastes. Show the message, keep the button available, and let onboarding continue. ## Frequently Asked Questions ### Why does a referral code get lost in the App Store on iPhone? The App Store does not pass the URL a person tapped to the app it installs. The first launch starts with no memory of the link, so a code in the query string is gone. An invitation page that copies the code, plus a paste step in the app, carries it across the install instead. ### Does the WarpLink SDK read the clipboard on iPhone? No. The person taps a system paste button, iOS asks them to allow the paste, and the SDK sees only the text that button hands over. Nothing else on the clipboard is read. ### Is the referral match exact when the person pastes? Yes. The pasted invitation carries an install token, so the match method is install_token and exact is true. With the iOS handoff on, an iPhone install with no paste earns no referral credit, because an estimated match is not accepted. With the handoff off, an estimate from device signals can be credited, and a later exact claim from the same person upgrades it. ### What if the person skips the paste step? Onboarding continues and the paste button stays on the screen. The app shows a referral as applied only when the SDK returns a link. With the iOS handoff on, a skipped paste earns no referral credit, and the person loses nothing in your app. ### Do I need a paste step on Android? No. Google Play hands the install referrer to the SDK on first launch, the invitation rides inside it, and the SDK matches it with no screen of yours. ## Related Guides - **The full referral path:** [Referrals](https://warplink.app/docs/guides/referrals) covers links, claims, the report, and troubleshooting. - **What Apple allows:** [Apple privacy rules and install matching](https://warplink.app/docs/trust/apple-privacy-and-matching) explains why this path needs no App Tracking Transparency prompt. - **The webhook side:** [Verify a referral before you grant the reward](https://warplink.app/blog/verify-referral-before-reward) turns the claim into a safe payout. - **The release:** [WarpLink SDK 1.2.0](https://warplink.app/blog/warplink-sdk-1-2-0) lists what shipped on all four SDKs. - **Use case:** [App referral programs](https://warplink.app/use-cases/app-referral-programs) and [invite-friends onboarding](https://warplink.app/use-cases/invite-friends-onboarding). - **The general mechanism:** [Deferred deep linking on iOS](https://warplink.app/blog/deferred-deep-linking-ios). ## How WarpLink Helps The parts of a referral you cannot host inside your app are the invitation page, the install token that proves the match, and the record that joins a tap to a first launch hours later. That is our job. You create a referral link, add one paste button, and call `claimReferral` after sign-up. We match it, keep the record, and send your backend a signed webhook. The reward and its rules stay in your system. One workflow, three pillars. Deep linking puts the tap on the right screen, install attribution credits the link that produced a new user, and real-time analytics shows referrals next to 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.