Referral System

Reward organic growth by attributing installs to users who shared Flinku links with a referrer id.

What it is

The referral system ties invite links to a stable referrerId in link params. When a new user installs and opens the app, your client reports the event to Flinku so the dashboard can show leaderboards and totals.

How it works

1. Create a link with params, e.g. {"{ referrerId: 'user_123' }"}.
2. The user shares the short URL (in-app share sheet, copy link, etc.).
3. A new user installs the app and opens it from that context.
4. After match(), the app calls POST /api/referrals/track with projectId, referrerId, and newUserId.
5. The dashboard shows a referral leaderboard for the project.

API endpoints

• POST /api/referrals/track — track a referral (no auth required)
• GET /api/referrals?projectId=X — leaderboard (auth required)
• GET /api/referrals/stats?projectId=X — aggregate stats (auth required)

Full schemas: Referrals API .

Flutter example

On first app open, after match(), if params include referrerId, report the referral:

// On app first open, after match():
final link = await flinku.match();
if (link != null && link.params['referrerId'] != null) {
  await http.post(
    Uri.parse('https://flku.dev/api/referrals/track'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'projectId': 'your-project-id',
      'referrerId': link.params['referrerId'],
      'newUserId': currentUser.uid,
    }),
  );
}