Flutter

Get your test keys

In the dashboard, go to Developers → API keys and copy your test publishable key (pk_test_…). You will also use your test secret key (sk_test_…) in step 6 to simulate the referred user from your terminal:

export INVITEBASE_SECRET_KEY=sk_test_...

Create a campaign

In Campaigns → New campaign, pick the Paid subscription template — it validates a referral when the referred user starts a paid subscription within 14 days, gated on a subscription_started event with plan: paid. Copy the campaign ID (for example 7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15).

Add the plugin

flutter pub add invitebase_flutter

dependencies:
  invitebase_flutter: ^1.0.0

The plugin is published to pub.dev. Supported platform versions and versioning details are in Flutter setup.

Configure and identify

Call configure before runApp. The SDK starts an anonymous session immediately — install, first open, and attribution bind to the anonymous ID, and identify merges that history onto your user after signup.

import 'package:invitebase_flutter/invitebase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Invitebase.configure(publishableKey: 'pk_test_...');
  runApp(const MyApp());
}

After signup or login:

await Invitebase.identify(InvitebaseUser(id: 'usr_123', email: 'sam@example.com'));

Get a referral link

import 'package:share_plus/share_plus.dart';

Future<void> invite() async {
  final link = await Invitebase.getReferralLink('7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15');
  // link.url  → https://mycompany.refr.link/a1b2c3
  // link.code → a1b2c3
  await Share.share(link.url);
}

Inbound attribution rides on the native SDKs underneath: the Play Install Referrer on Android, the clipboard handoff and Universal Links on iOS. If a link opens the app directly (via go_router, app_links, or your own handler), pass it through:

Invitebase.handleInbound(uri);

Manual entry is available as a fallback with Invitebase.applyCode('a1b2c3'). One-time domain association for Universal Links and App Links is covered in deep-link attribution — you can finish this quickstart without it.

Simulate the referred signup and qualifying event

Play the friend from your terminal. First the signup, carrying the referral code for attribution, then the qualifying event:

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signup",
    "referred_user_id": "usr_friend_1",
    "referral_code": "a1b2c3"
  }'

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subscription_started",
    "referred_user_id": "usr_friend_1",
    "properties": { "plan": "paid" }
  }'

You can fire the same events from Developers → Event simulator instead. In the real app, the referred user's device sends the qualifying event with one call:

Invitebase.track('subscription_started', {'plan': 'paid'});

Watch it validate

Open the dashboard Overview: both events land in the live feed, and the referral moves signed_up → in_progress → validated under your campaign.

In the app, subscribe to the change streams so widgets rebuild the moment state changes — no polling:

StreamBuilder(
  stream: Invitebase.referralStateChanged,
  builder: (context, snapshot) {
    final change = snapshot.data;
    // 5f8e2a1d-… → ReferralStatus.validated
    return Text(change?.status.name ?? 'waiting…');
  },
)

Invitebase.rewardsChanged fires the same way when a reward is earned — the confetti moment.