Deep Links & Attribution Setup

Register your app identity

In Settings → Attribution, enter your Apple Team ID and bundle ID. Invitebase generates and serves the apple-app-site-association (AASA) file for your subdomain — you never host it.

Add the Associated Domains entitlement

This is the one step only you can do — it is an OS requirement. In Xcode, under Signing & Capabilities → Associated Domains, add:

applinks:mycompany.refr.link

Enable the Associated Domains capability for your App ID in the Apple Developer portal if it is not already, then ship an app update. From then on, a tapped referral link opens your app directly with the code intact.

Handle inbound links

import InvitebaseSDK

// At launch
Invitebase.configure("pk_live_...")

// Universal Link arrives while installed
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if let url = userActivity.webpageURL {
        Invitebase.handleInbound(url) // parses the code and applies it
    }
    return true
}

Note: Universal Links only trigger on a real user tap — JavaScript or 302 redirects do not open the app. The refr.link offer page is built around this.

Deferred attribution (fresh installs): clipboard handoff

iOS has no install referrer, so Invitebase uses a deterministic first-party clipboard handoff — no ATT consent, no permission-priming, no fingerprinting:

1. When the invitee taps the CTA on the offer page, the page writes the invite URL to the clipboard (inside the tap gesture, as Safari requires) and hands off to the App Store.
2. On first launch, call resolveReferral(). The SDK silently checks whether the clipboard contains a URL (detectPatterns — never prompts, never reads content), and only then surfaces a system Paste button (UIPasteControl), which shows no permission modal. The SDK only accepts URLs on your configured refr.link/custom domain — an arbitrary copied URL is never treated as a referral.
3. If the clipboard misses or the user declines, the SDK falls back to code entry, tiered by signal: a strong "paste or enter your invite code" prompt when a URL was present but unreadable, or a soft, skippable "Have an invite code?" field otherwise — so organic users are never pestered.

let result = await Invitebase.resolveReferral()
switch result {
case .attributed(let code):
    showWelcome(for: code) // e.g. "You were invited — your free month is active"
case .needsManualEntry(let signal):
    presentCodeEntry(prominence: signal) // SDK ships a themeable default screen
case .organic:
    break
}

Resolution is one-shot: once attribution resolves, the SDK persists a flag and never touches the clipboard again. Call resolveReferral() early — clipboards are volatile — but surface any UI at a contextual onboarding moment.

Deferred attribution: Install Referrer (automatic)

Android is the easy platform. The offer page routes invitees to the Play Store with the code in the referrer= parameter, and the Play Install Referrer API passes it through install deterministically — no prompt, no clipboard, near-100% match. The SDK recovers it on first launch:

Invitebase.configure("pk_live_...")
val result = Invitebase.resolveReferral() // reads Install Referrer once, then never again

No configuration required. The referrer string is only present for Play Store installs — sideloads fall back to manual code entry.

App Links for installed users

In Settings → Attribution, enter your package name and SHA-256 signing certificate fingerprints (include the Play App Signing certificate). Invitebase serves /.well-known/assetlinks.json on your subdomain.

Then declare the intent filter:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="mycompany.refr.link" />
</intent-filter>

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { Invitebase.handleInbound(it) }
}