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 friend starts a paid subscription within 14 days, which your app reports as 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 right away, so the install, first open and attribution are recorded before signup. identify moves that history onto your user.

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 SharePlus.instance.share(ShareParams(text: link.url));
}

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

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 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, listen to the change streams so your widgets rebuild when the referral changes. You don't need to poll:

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.