Users and identity

Invitebase tracks your app's end-users — the referrers who share and the referred users who join — with an anonymous-first identity model. The SDK works fully before anyone logs in, because the referred user's most important moments (install, first open, attribution, early qualifying actions) almost always happen before signup. If tracking started at login, the front of every referral funnel would be lost.

Anonymous IDs

At configure(key), the SDK generates a stable per-install anonymous ID and persists it in platform-appropriate secure storage (Keychain on iOS, EncryptedSharedPreferences on Android, localStorage on web). From that moment everything works anonymously:

• track(event, props) records events against the anonymous ID.
• Attribution — resolveReferral(), handleInbound(url), applyCode(code) — binds the referral to the anonymous ID.
• Gate progress accumulates against it.

A reinstall generates a new anonymous ID (the storage is per-install); attribution's one-shot flags and server-side dedup keep reinstalls from double-attributing.

identify(): aliasing, not switching

When the user signs up or logs in, call identify with your own stable ID for them:

invitebase.identify({
  externalId: 'usr_482',        // your ID for this user — the join key
  email: 'maya@example.com',    // optional, powers self-referral detection
  name: 'Maya',
});

identify() merges rather than replaces: the anonymous history — events, referral attribution, gate progress — is aliased onto the identified user server-side. Events ingested under the anonymous ID count toward qualification after the merge, so a user who installed, got attributed, and completed onboarding before creating an account still qualifies on all of it.

The merge is idempotent and handles the orders that happen in real apps: attribute → events → identify; identify → more events; identifying into an existing user who already has history; and two devices identifying as the same user. One deliberate side effect: unusual linkage patterns (many anonymous IDs merging into one user) are themselves a signal weighed by fraud verification.

External IDs

Your externalId is the join key between your systems and Invitebase — the same value you use in your own database, sent on server-side events as referred_user_id, returned in webhooks, and searchable in the dashboard. Invitebase assigns its own object IDs (plain UUIDs, with your usr_…-style external ID shown alongside), but you never have to store them: every API surface accepts and returns your external ID.

Creating a referrer server-side is idempotent on external_id within an org and mode — call it whenever a user could become a referrer:

curl https://api.invitebase.com/v1/referrers \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "usr_291", "email": "sam@example.com", "name": "Sam" }'

Referrers vs. referred users

The same person can play both roles, and Invitebase models them as directions on one identity rather than two records:

• A referrer is a user who shares — they own referral links and earn (give-side) rewards.
• A referred user is a user who came in through a link or code — they progress through gates and may receive a (receive-side) reward in two-sided campaigns.

A user referred in January can become your best referrer in February; both histories live on the same profile.

The Users dashboard

The Users tab at dashboard.invitebase.com lists every end-user who has touched your referral surface — was shown the invite screen, referred someone, or was referred — with at-a-glance columns:

Search by name, email, or external ID; filter by reward status and direction. Each row opens a user profile: identity header with copyable external ID, first-seen and last-activity, a chronological timeline of invite-screen interactions and referral events (clicked, signed up, validated, reward paid, rejected), rewards received and given, and payout history with statuses — with links out to the related campaigns, referrals, and payouts.

The profile is your support surface: when a user writes in with "my friend signed up but I never got my reward", the timeline shows exactly which gate is unsatisfied, or which fraud rule rejected the referral.

Privacy posture

Invitebase is a data processor for your end-users and stores only what the product needs: identity fields you send, events, device signals used by fraud checks, and payout details where monetary payouts are enabled. No fingerprinting is used for attribution anywhere — see Attribution. Per-user data export and erasure endpoints support your GDPR/CCPA obligations.