Invitebase | Configure & identity

configure, identify, reset, setPushToken, and setNotificationPreferences — initializing the SDK and managing the current user

Every integration starts here: configure initializes the SDK with your publishable key, identify attaches your user ID once someone signs up, and reset clears the identity on logout. The SDK is anonymous-first — everything works before identify is ever called, and the anonymous history merges when it is.

Pick your platform once — every code sample in the reference follows it.

configure

Initializes the SDK. Call once, as early as possible in your app's lifecycle — before any other Invitebase call. Generates (or restores) the anonymous ID from platform storage and, by default, starts inbound referral resolution.

Parameter	Type	Description
`publishableKey`	string	Your publishable key (`pk_test_…` or `pk_live_…`). The prefix determines test vs live mode.
`autoResolve`	boolean	Run inbound attribution automatically. Default `true`. Set `false` to control the moment yourself with `resolveReferral()`.
`debugLogging`	boolean	Log SDK activity (named `debug` on Web and React Native). Default `false`.

invitebase.configure(publishableKey: string, options?: ConfigureOptions): void

lib/invitebase.ts

import invitebase from '@invitebase/js';

invitebase.configure(process.env.NEXT_PUBLIC_INVITEBASE_PUBLISHABLE_KEY, { debug: true });

export default invitebase;

Restores the anonymous ID from localStorage and immediately checks the current URL and stored cookie for an inbound referral code.

Invitebase.configure(publishableKey: String, options: InvitebaseOptions? = nil)

MycompanyApp.swift

@main
struct MycompanyApp: App {
    init() {
        Invitebase.configure(publishableKey: "pk_test_51Hq2jK")
    }
    // …
}

Restores the anonymous ID from the Keychain and schedules clipboard-handoff resolution for first launch. UIKit wiring in iOS setup.

Invitebase.configure(context: Context, publishableKey: String, options: InvitebaseOptions? = null)

MycompanyApplication.kt

class MycompanyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Invitebase.configure(this, "pk_test_51Hq2jK")
    }
}

Call in Application.onCreate() (register the class in your manifest — see Android setup). Restores the anonymous ID from EncryptedSharedPreferences and, on first launch only, queries the Play Install Referrer.

<InvitebaseProvider publishableKey={string} autoResolve={boolean} debug={boolean}>

App.tsx

import { InvitebaseProvider } from '@invitebase/react-native';

export default function App() {
  return (
    <InvitebaseProvider publishableKey="pk_test_51Hq2jK">
      <RootNavigator />
    </InvitebaseProvider>
  );
}

React Native configures via the provider component, which calls configure natively and makes the hooks work anywhere below it.

static Future<void> Invitebase.configure({
  required String publishableKey,
  bool autoResolve = true,
  bool debugLogging = false,
})

main.dart

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

Call before runApp. Identity storage and attribution run in the native SDKs underneath — see Flutter setup.

identify

Attaches your user ID to the current person and merges their anonymous history — attribution, events, and gate progress recorded before login all carry over. Idempotent: identifying the same user twice is a no-op, and every ordering of attribute → events → identify merges correctly. See Users & identity.

Parameter	Type	Description
`user.id`	string	Required. Your stable ID for this user.
`user.email`	string	Optional. Used for self-referral and disposable-email fraud checks.
`user.name`	string	Optional. Privacy-safe display name shown to invitees ("You were invited by Andrew").
`user.traits`	map	Optional. Arbitrary properties.

invitebase.identify(user: InvitebaseUser): Promise<void>

await invitebase.identify({
  id: 'usr_123',
  email: 'dana@example.com',
  name: 'Dana',
});

Invitebase.identify(_ user: InvitebaseUser) async throws

try await Invitebase.identify(
    InvitebaseUser(id: "usr_123", email: "dana@example.com", name: "Dana")
)

suspend fun Invitebase.identify(user: InvitebaseUser)

lifecycleScope.launch {
    Invitebase.identify(
        InvitebaseUser(id = "usr_123", email = "dana@example.com", name = "Dana")
    )
}

identify(user: InvitebaseUser): Promise<void>

const invitebase = useInvitebase();

await invitebase.identify({ id: 'usr_123', email: 'dana@example.com', name: 'Dana' });

static Future<void> Invitebase.identify(InvitebaseUser user)

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

Throws an SDK error on failure.

reset

Clears the current identity (and any stored referral code) and starts a fresh anonymous session. Call on logout.

invitebase.reset(): void

Invitebase.reset()

fun Invitebase.reset()

reset(): void

static Future<void> Invitebase.reset()

No parameters.

setPushToken

Forwards the device's push token so Invitebase can send referral push notifications directly to this device. This wires up the Invitebase-managed delivery mode — the default, chosen per app in Settings. If you bring your own push provider instead (planned, not yet available), you will not call this: device tokens stay on your side, and Invitebase will hand each notification to your backend as a notification.due webhook.

Register for remote notifications as usual, then call setPushToken any time after configure — the token attaches to the current user, anonymous or identified, and merges onto the identified user like everything else.

Tokens are stored per user, per device: a referrer with two devices gets the push on both. Call it again whenever the platform rotates the token — the stored token is kept current — and stale tokens are pruned automatically via APNs/FCM feedback. Delivery also requires your push credentials (APNs .p8 key for iOS, FCM service-account key for Android) uploaded in Settings.

Parameter	Type	Description
`token`	Data / string	The APNs device token (iOS) or FCM registration token (Android).

Not applicable — Invitebase push delivery targets iOS and Android device tokens, so there is nothing to register on Web. Web users are still reachable by email.

Invitebase.setPushToken(_ deviceToken: Data)

AppDelegate.swift

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    Invitebase.setPushToken(deviceToken)
}

Pass the raw Data from the registration callback — the SDK handles encoding. iOS delivers the token on every launch registration; forwarding it each time is expected, and a no-op when unchanged. Wiring notes in iOS setup.

fun Invitebase.setPushToken(token: String)

MycompanyMessagingService.kt

class MycompanyMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Invitebase.setPushToken(token)
    }
}

onNewToken fires only on generation and rotation, so also forward the current token once after configure — see Android setup.

setPushToken(token: string): Promise<void>

import * as Notifications from 'expo-notifications';

const invitebase = useInvitebase();

const { data: token } = await Notifications.getDevicePushTokenAsync();
await invitebase.setPushToken(token);

Forward the native device token — APNs on iOS, FCM on Android. Any push library that exposes it works; see React Native setup.

static Future<void> Invitebase.setPushToken(String token)

final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();
if (token != null) await Invitebase.setPushToken(token);

Forward the native device token — the APNs token on iOS, the FCM registration token on Android. Wiring notes in Flutter setup.

setNotificationPreferences

Sets the current user's referral-notification preferences — whether Invitebase may email or push them about referral activity (triggers). Both channels default to on. Preferences are stored server-side per user, checked before every dispatch, and survive re-identification and new devices. Set for an anonymous user, they merge onto the identified user like everything else.

Parameter	Type	Description
`preferences.email`	boolean	Allow referral emails. Default `true`.
`preferences.push`	boolean	Allow referral push notifications. Default `true`.

Omitted channels are left unchanged, so a single toggle can flip one channel without touching the other.

invitebase.setNotificationPreferences(preferences: NotificationPreferences): Promise<void>

await invitebase.setNotificationPreferences({ email: false, push: true });

Invitebase.setNotificationPreferences(_ preferences: NotificationPreferences) async throws

try await Invitebase.setNotificationPreferences(
    NotificationPreferences(email: false, push: true)
)

suspend fun Invitebase.setNotificationPreferences(preferences: NotificationPreferences)

lifecycleScope.launch {
    Invitebase.setNotificationPreferences(
        NotificationPreferences(email = false, push = true)
    )
}

setNotificationPreferences(preferences: NotificationPreferences): Promise<void>

const invitebase = useInvitebase();

await invitebase.setNotificationPreferences({ email: false, push: true });

static Future<void> Invitebase.setNotificationPreferences(NotificationPreferences preferences)

await Invitebase.setNotificationPreferences(
  NotificationPreferences(email: false, push: true),
);

Throws an SDK error on failure. The same preferences are settable server-side via POST /v1/referrers.

What's next

Referral links

getReferralLink — create and share the current user's referral link.

Attribution

handleInbound, resolveReferral, and applyCode — how codes reach the SDK.

Events

track — record the events qualification gates evaluate.

Campaigns & progress

getCampaignInfo and getReferrerProgress — the offer and current standing.