iOS setup

InvitebaseSDK is the native Swift SDK for iOS, distributed via Swift Package Manager or as a downloadable XCFramework. This page covers a quick-start guide to install the SDK into your SwiftUI or UIKit project.

For a guided approach to setup, install, and launch, please see the iOS quickstart.

Install

dependencies: [
    .package(url: "https://github.com/invitebase/invitebase-ios", from: "1.0.0")
]

Then import it:

import InvitebaseSDK

The SDK supports iOS 15+ and follows semver.

Configure at launch

Call configure once at launch — before any other Invitebase call. It generates (or restores) the anonymous ID from the Keychain and schedules deferred-attribution resolution for first launch.

import SwiftUI
import InvitebaseSDK

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

    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    Invitebase.handleInbound(url)
                }
        }
    }
}

import UIKit
import InvitebaseSDK

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Invitebase.configure(publishableKey: "pk_test_51Hq2jK")
        return true
    }
}

Universal Links setup

Universal Links are the already-installed path: a friend taps https://mycompany.refr.link/a1b2c3, iOS opens your app directly, and you hand the URL to handleInbound.

Invitebase serves the apple-app-site-association file for your {app}.refr.link subdomain — you never host anything. Your one required step is the Associated Domains entitlement:

1. In the dashboard under Settings → Attribution, enter your Apple Team ID and bundle ID.
2. In Xcode, add the Associated Domains capability with applinks:mycompany.refr.link (your subdomain).
3. Ship an app update, then wire the callbacks:

WindowGroup {
    ContentView()
        .onOpenURL { url in
            Invitebase.handleInbound(url)
        }
        .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
            if let url = activity.webpageURL {
                Invitebase.handleInbound(url)
            }
        }
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
       let url = userActivity.webpageURL {
        Invitebase.handleInbound(url)
    }
}

func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {
    if let activity = connectionOptions.userActivities.first,
       let url = activity.webpageURL {
        Invitebase.handleInbound(url)
    }
}

How the clipboard handoff works

The clipboard handoff is iOS's deferred-attribution path, reported by resolveReferral: when an invitee taps the CTA on the refr.link page, the invite URL is written to their clipboard before the App Store handoff; on first launch the SDK recovers it.

The flow is deterministic and never shows a permission modal when integrated as recommended:

1. Silent presence check — the SDK calls UIPasteboard.detectPatterns(.probableWebURL), which never prompts and returns no content. Paste UI only ever appears when a URL is actually on the clipboard.
2. User-initiated read — the SDK's paste affordance embeds UIPasteControl, Apple's system Paste button. Because the read is user-initiated, iOS shows no permission prompt.
3. Host allow-list — a clipboard URL only counts as a referral if its host matches your refr.link domain. An arbitrary copied URL is never attributed.
4. Outcome discrimination — a declined read (PBErrorDomain code 13) maps to needsManualEntry with a strong signal; an empty or non-matching clipboard maps to organic or a soft signal. Declined is never confused with empty.
5. One-shot — once a code is recovered and applied, the SDK persists an attribution-resolved flag and never reads the clipboard again on later launches.

Resolve early — the clipboard is volatile between install and first launch — but surface paste UI at a contextual onboarding moment. Field acceptance runs 60–90%; every branch emits telemetry so your attribution funnel shows the measured rate, and the manual-entry fallback catches the rest.

Paste affordance and code entry UI

The SDK ships two drop-in views:

// System paste button (UIPasteControl) wired to attribution — no permission prompt
InvitebasePasteButton { resolution in
    handle(resolution)
}

// Themeable manual code-entry screen with validation states,
// strong/soft prominence variants, and an embedded paste control
InvitebaseCodeEntryView(prominence: .strong) { result in
    handle(result)
}

Both are themeable from your per-campaign configuration and fully replaceable: the underlying validation runs through applyCode, so custom UI loses nothing.

Push notifications

If you use Invitebase-managed referral push notifications — the default delivery mode — forward the APNs device token after registering for remote notifications; Invitebase sends directly through APNs with the .p8 key you upload in Settings:

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

SwiftUI apps receive this callback through a UIApplicationDelegateAdaptor. iOS delivers the token on every launch registration; the SDK attaches it to the current user and keeps it current across rotations. Details in setPushToken.

Bringing your own push provider instead? Skip this — device tokens stay on your side, and Invitebase will hand each notification to your backend as a notification.due webhook (bring-your-own-push is planned, not yet available).

What's next