Flutter Referral System: Invite Links and Install Credit

To build a referral system in Flutter, mark a link as a referral link, let the new person open it, and call two static methods: WarpLink.redeemInvitation on iPhone and WarpLink.claimReferral at sign-up. The SDK matches the install to the sharing link. A signed webhook then tells your server to grant the reward.

This guide uses warplink_flutter 1.2.0. The reference version lives in the Flutter referral quickstart.

How a Flutter referral works

A friend shares an invite link. The new person taps it, installs the app, opens it, and signs up. Your app needs to know which link brought them. The two platforms differ:

• Android. Google Play stores the invitation in the install referrer, and the plugin reads it at first launch. The match is exact (android_referrer) and shows no screen. Android install referrer referral code in Kotlin shows what happens underneath.
• iPhone. An App Store install carries no data. The invite page puts the invitation on the clipboard, and your app asks the person to paste it. The match is exact (install_token). Make a referral link survive the App Store on iPhone explains the iPhone side.

Both end in the same call, claimReferral, so the rest of your Dart code is one path.

Install the SDK

flutter pub add warplink_flutter

This adds warplink_flutter: ^1.2.0 to pubspec.yaml. SDK 1.1.x cannot read an invitation. You need Flutter 3.38 or later and Dart 3.10 or later, and the plugin runs on iOS and Android.

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

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 later, and the id tells you whose invitation earned the credit.

Configure the SDK once

Call configure from your root widget's initState, so it runs once per launch:

import 'package:warplink_flutter/warplink_flutter.dart';

@override
void initState() {
  super.initState();
  WarpLink.configure(
    apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
    onLink: (event) {
      if (event is LinkEvent && event.deepLink.isDeferred) {
        showWelcomeFromInvitation(event.deepLink);
      }
    },
  );
}

On Android, the referrer match arrives in onLink like any other deferred link.

Redeem the invitation on iPhone

The Flutter package has no paste button widget. The SDK never reads the clipboard itself, and it sees only the text you pass in. Show a text field on your first screen, ask the person to paste the invitation, and pass the text to redeemInvitation:

final controller = TextEditingController();

Future<void> apply() async {
  try {
    final link = await WarpLink.redeemInvitation(controller.text);
    if (link != null) showApplied(); // null: not an invitation, or no match
  } on WarpLinkServerException catch (error) {
    showMessage(error.message); // says how to open the link again
  } on WarpLinkNetworkException {
    showMessage('Check your connection and try again.');
  }
  finishOnboardingStep();
}

Column(children: [
  TextField(
    controller: controller,
    decoration: const InputDecoration(hintText: 'Paste your invitation'),
    maxLines: 3,
  ),
  ElevatedButton(onPressed: apply, child: const Text('Apply')),
  TextButton(onPressed: finishOnboardingStep, child: const Text('Skip')),
])

Two rules keep this honest. The paste step is an offer, not a gate, so keep the skip button and let onboarding continue when redeemInvitation returns null or throws. And do not read the clipboard in the background to fill the field: iOS asks the person to allow a paste your app starts, and the person should see why.

After a WarpLinkNetworkException, the native SDK keeps the invitation and tries again on a later launch. That later result arrives through getAttributionResult() and claimReferral, not onLink.

Claim the install at sign-up

When the new person signs up, call claimReferral with an installer id: a dedicated random id for that user, 1 to 128 characters. Do not use a primary key, an email address, or a phone number.

Future<ReferralClaimResult?> claimForNewUser(String installerId) async {
  try {
    return await WarpLink.claimReferral(installerId);
  } on WarpLinkException catch (error) {
    // Unreachable server, refused key, or an empty or too long installer id.
    reportError(error);
  }
  return null;
}

Failures arrive as subclasses of WarpLinkException, so one on WarpLinkException clause covers them all. Catch WarpLinkNetworkException first if you want to retry only when the server was unreachable.

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

final claim = await claimForNewUser(user.warplinkId);
switch (claim?.status) {
  case ReferralClaimStatus.claimed:
    break; // credited inside the window
  case ReferralClaimStatus.flagged:
    break; // credited after the window: claim.flags has "outside_window"
  case ReferralClaimStatus.ignored:
    break; // already credited: see claim.duplicateOf
  case ReferralClaimStatus.none:
  case null:
    break; // no referral link brought this install, or the call failed
}

none is an ordinary answer, not an error. The result also carries referralId, linkId, matchMethod, isExact, matchConfidence, flags and duplicateOf.

Grant the reward from the webhook

Your server receives a signed referral.claimed event within seconds of the claim. Verify the signature on the raw body, skip an event id you have already seen, then grant the reward from your own rules:

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

The reward itself stays in your system. Receive a referral reward webhook in Node.js and in Python show the receiver, and Verify a referral before you grant the reward lists the checks to run first. 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.

If the reward is store credit or a subscription month, read App Store and Google Play referral reward rules first.

Test it

Test on a real phone. On Android, install from a Google Play internal testing track. On iPhone, install from TestFlight or the App Store, then paste the invitation. How to test the install referrer and referral links has the full steps, the webhook test, and the Referrals report checks.

Frequently Asked Questions

How do I build a referral system in Flutter?

Add warplink_flutter 1.2.0, mark a link as a referral link, call redeemInvitation on iPhone, and call claimReferral when the new person signs up. A signed webhook then tells your server to grant the reward.

How do I read the Google Play install referrer in Flutter?

You do not need to. The WarpLink plugin reads the Play install referrer on Android at first launch and matches it to the sharing link. The match is exact and shows no screen.

What exceptions does claimReferral throw in Flutter?

Failures arrive as subclasses of WarpLinkException. WarpLinkNetworkException means the server was unreachable. WarpLinkServerException covers a refused claim, such as an empty installer id or a 4xx answer from the server.

Does Flutter have a system paste button for the iPhone invitation?

The Flutter package has no paste button widget. Use a plain text field where the person pastes the invitation. The SDK never reads the clipboard and sees only the text you pass in.

Can the same user claim a referral twice?

No. The first valid claim for an app and installer id wins. A later claim returns status ignored with a duplicateOf reference, so a reward is never granted twice from our side.

Related Guides

• Quickstart: Flutter referral quickstart and the full referrals guide.
• Other platforms: Android install referrer referral code, React Native referral program, and referral links on iPhone.
• Test it: How to test the install referrer and referral links.
• Flutter deep links: Flutter deep linking and deferred deep linking in Flutter.
• Choosing an approach: Best ways to add a referral program to a mobile app.

How WarpLink Helps

One plugin covers both stores. The same two calls work on Android and iPhone, the match is exact on both, and every claim shows in the Referrals report with its webhook deliveries. The reward and its rules stay in your system.

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 and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.