Flinku Docs
Go to Dashboard

Referral system

Attribute installs and qualified actions to users who shared Flinku links, even when the App Store or Play Store breaks the click path. SDK 0.6.0 tracks referrals automatically.

What deferred referral attribution is

Deferred referral attribution means: user A shares an invite link, user B taps it, installs your app from the store, and you still know A brought them. The link carries referrerId (and optionally referrerLabel) in its params so Flinku can credit the right person.

An App Store or Play Store install breaks normal tracking. The store opens a fresh session; the original URL is gone. Flinku's deferred match() recovers which link was clicked before install. When the new user signs up, you call setUserId. The SDK attributes the referral itself. You never call the track API from your app.

Setup

1. Create a link with referrer params

Include referrerId (required for attribution) and optional referrerLabel (shown in the dashboard). You can create the link from the dashboard, your backend, or the SDK.

dart
final link = await Flinku.createLink(FlinkuLinkOptions(
  title: 'Invite from Alice',
  deepLink: 'myapp://home',
  params: {
    'referrerId': 'user_123',
    'referrerLabel': 'Alice',
  },
));
print(link.shortUrl);

2. Pass apiKey at initialization (required for referrals)

⚠️Warning
Pass your publishable key flk_pk_... when initializing the SDK: Flinku.configure() on Flutter, iOS, and Android; new Flinku({ ... }) on React Native and Capacitor. Without it, referral tracking silently does nothing. setUserId and qualifyReferral will not hit the network. Do not embed your secret key (flk_live_) in the app.
dart
Flinku.configure(
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...', // required for referrals
);

3. Call setUserId after signup or login

Call once after the referred user signs up or logs in. The SDK reads the pending referral written at match time and reports it automatically. Fire-and-forget: returns immediately and never throws into your caller.

dart
// After signup or login, the SDK tracks the referral automatically
Flinku.setUserId(user.id);

Optional: qualifyReferral

When the referred user does the thing you actually reward, call qualifyReferral with an event name. Also fire-and-forget.

dart
Flinku.qualifyReferral('purchase');

Why qualifyReferral exists

Rewarding on install is the most gameable moment. Fake installs, device farms, and throwaway accounts inflate counts before anyone does anything real. The qualifying event should sit far enough down your funnel that repeating it is painful, so reward on something valuable, not on first open.

Examples:

  • First purchase
  • First meal logged
  • First workout completed

Fraud protection

Self referrals, duplicate devices, and abnormal velocity are flagged automatically and excluded from qualified counts. No developer configuration needed. Flagged rows still appear in the dashboard for review; they do not count toward Qualified.

Webhook

Set referralWebhookUrl on the project. When a referral is qualified, Flinku POSTs:

payload
{
  "projectId": "proj_…",
  "referrerId": "user_123",
  "referrerLabel": "Alice",
  "newUserId": "user_456",
  "qualifyEvent": "purchase",
  "qualifiedAt": "2026-07-13T12:00:00.000Z"
}

Flinku does not handle payouts. Credit your own user when you receive this webhook: grant coins, unlock a perk, or write a commission row in your system.

⚠️Warning
Your receiving endpoint must authenticate the request (shared secret header, HMAC, IP allowlist, or similar). Treat an unauthenticated webhook URL as open to abuse.

reset() and referral attribution

reset() clears the cached match result only. It does not clear the stored user id or pending referral attribution. This changed in 0.6.0. Calling reset() after routing a deep link is safe — setUserId can still track the referral afterward.

Use the form for your SDK:

  • Flutter: await Flinku.reset()
  • iOS: Flinku.reset()
  • Android: Flinku.reset(context)
  • React Native: await flinku.reset()
  • Capacitor: await flinku.reset()
  • Unity: FlinkuSDK.Instance.Reset()

resetAll()

Clears everything reset() clears, plus the stored user id, referral project id, all pending referral records, and any tracked-once markers. Testing only — do not call in production. Calling it in production destroys real referral attribution. Added in 0.7.0.

Use the form for your SDK:

  • Flutter: await Flinku.resetAll()
  • iOS: Flinku.resetAll()
  • Android: Flinku.resetAll(context)
  • React Native: await flinku.resetAll()
  • Capacitor: await flinku.resetAll()
  • Unity: FlinkuSDK.Instance.ResetAll()

API reference

Apps should use setUserId and qualifyReferral. The endpoints below exist for the SDK and for server-side use, not as something you wire up by hand in the mobile client.

  • POST /api/referrals/track: called automatically by the SDK after setUserId
  • POST /api/referrals/qualify: called by the SDK after qualifyReferral
  • GET /api/referrals: funnel and referrers (dashboard / authenticated)

Full schemas: Referrals API.