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 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 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 right away, because a friend's install, first open and attribution all happen before they sign up. identify later moves that history 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 doesn't pass the link through an App Store install. So when the friend taps through to the App Store, the refr.link page copies the referral link to the clipboard, and the SDK picks it up on first launch. 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"); prebuilt code-entry UI is coming soon, so use your own entry screen for launch.

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 clipboard details are 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 your app when it validates, adopt the delegate:

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