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.

All five SDKs ship as version 1.0 on November 15, 2026. Prebuilt UI components and push notifications are coming soon and are outside the November 15 release. Build custom UI with the SDK methods and reactive reads.

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

Prebuilt referral screens, including InvitebaseCodeEntryView, are coming soon. For launch, build custom code-entry UI over applyCode. Use Apple's system UIPasteControl for user-initiated clipboard access.

Push notifications

Coming soon. Push notifications and setPushToken are outside the November 15 release. Use email notifications for launch.

What's next