iOS

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 7 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 package

In Xcode, choose File → Add Package Dependencies… and add:

https://github.com/invitebase/invitebase-ios

Select the InvitebaseSDK product. Supported iOS versions, the Package.swift form, and versioning details are in iOS setup.

Configure and identify

Call configure once at launch. The SDK starts an anonymous session immediately — the referee's most important moments (install, first open, attribution) happen before signup, and they all bind to the anonymous ID until identify merges them onto your user.

import InvitebaseSDK

@main
struct MyApp: App {
    init() {
        Invitebase.configure(publishableKey: "pk_test_...")
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

After signup or login:

try await Invitebase.identify(.init(id: "usr_123", email: "sam@example.com"))

Get a referral link

let link = try await Invitebase.getReferralLink(campaignId: "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15")

// link.url  → https://mycompany.refr.link/a1b2c3
// link.code → a1b2c3

Put link.url behind your "Invite a friend" button — a plain ShareLink(item: link.url) is enough for the quickstart.

Wire the inbound paths

A referred friend arrives one of two ways, and each needs one call.

Friend already has the app — the link opens it directly via Universal Links. Pass the URL to the SDK:

WindowGroup {
    ContentView()
        .onOpenURL { url in
            Invitebase.handleInbound(url)
        }
}

Friend installs the app — iOS has no install referrer, so Invitebase uses a deterministic clipboard handoff: the refr.link page copies the referral URL when the friend taps through to the App Store, and on first launch the SDK recovers it. Call this once when your app first runs:

Task {
    let referral = await Invitebase.resolveReferral()
    // .attributed(InboundReferral) / .needsManualEntry(signal:) / .organic
}

resolveReferral checks the clipboard using Apple's pattern-detection APIs — no fingerprinting, no ATT prompt. If the read misses or the user declines, fall back to manual entry with Invitebase.applyCode("a1b2c3"); the SDK also ships a themeable code-entry screen.

Universal Links need the Associated Domains entitlement for your refr.link subdomain (Invitebase serves the AASA file for you). That one-time setup, and the details of the clipboard flow, are 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", properties: ["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. To react in-app the moment it happens — the confetti moment — adopt the delegate:

extension AppModel: InvitebaseDelegate {
    func referralStateDidChange(_ referral: ReferralUpdate) {
        // 5f8e2a1d-… → .validated
    }
}