Tracking

Attribution

Rift tracks the full funnel: click → install → identify → convert. The SDKs handle most of this automatically. Attribution endpoints use a publishable key (pk_live_).

How it works

Four SDK calls map 1:1 to four HTTP endpoints and four webhook event types. Call them in funnel order as the user moves through your product — Rift records each step, materializes the install state, and fires a webhook your backend can react to.

SDK callHTTP endpointstorage writewebhook firedfunnel order

Solid arrows are synchronous: each SDK call hits one endpoint, which writes to one (sometimes two) collections and dispatches one webhook. Dashed arrows are funnel order — they happen later in the user's journey, often on a different device or session. The four verbs are independent: you can call any of them at any time, in any order.

What's tracked automatically

Every time a user hits a Rift link — whether on the landing page, via a custom domain, or through the shared riftl.ink domain — Rift records the click automatically. No SDK call is needed for this. The click captures platform, user agent, and referrer.

The SDK-based click recording (below) is for additional tracking — in-app link taps, programmatic navigation, or cases where you want the click response data.

Direct redirect mode

By default, Rift serves a smart landing page that detects the user's platform and shows “Open in App” / store buttons. If you want to skip the landing page and send the user directly to their platform destination, add ?redirect=1 to the link URL:

https://go.yourcompany.com/summer-sale?redirect=1

This still records the click, then immediately redirects:

Platform	Redirects to
iOS	App Store URL
Android	Play Store URL with `referrer=rift_link={link_id}` appended for install attribution
Desktop	Web URL

Note: Use redirect=1 when you want the fastest path to the destination — for example, in email campaigns or QR codes where a landing page adds friction. The click is still tracked, but the user never sees the landing page.

SDK click reporting

The Web SDK auto-tracks clicks on any <a> tag pointing to your custom domain. No extra code needed after Rift.init().

// Auto-tracking is enabled by default after init
Rift.init("pk_live_YOUR_KEY", {
  domain: "go.yourcompany.com",
});

// For programmatic use (buttons, custom UI):
Rift.click("summer-sale");

On click, the SDK fires a sendBeacon request to POST /v1/lifecycle/click and copies the link URL to the clipboard. The beacon is fire-and-forget — it doesn't block navigation.

Note: The clipboard write is how iOS deferred deep linking works. When the user installs the app and opens it, the iOS SDK reads the link ID from the clipboard.

Attribute the touch

attribute records that an install touched a link — whether it's a fresh install whose first-touch you're capturing, or an already-signed-in user clicking a new campaign link. Every call appends an event; first-touch attribution stays sticky for stats. On mobile the SDK recovers the link ID after install — the mechanism differs by platform.

iOS — Clipboard

The landing page (or Web SDK) writes the link URL to the clipboard. On first launch, the iOS SDK reads the clipboard, extracts the link ID, reports attribution, and clears the clipboard.

Android — Install Referrer

The landing page appends rift_link={link_id} to the Play Store URL. On first launch, the SDK reads the install referrer and reports attribution.

Report attribution

The simplest path is checkDeferredDeepLinkFromPasteboard — it detects a URL on the pasteboard (without reading it unless one is present), reports attribution, and returns the link data in one call:

// On first app launch
if let result = try await rift.checkDeferredDeepLinkFromPasteboard() {
    if let deepLink = result.iosDeepLink {
        handleDeepLink(deepLink)
    }
}

Or use the lower-level method if you need more control:

let reported = try await rift.attributeLink(linkId: "summer-sale")

Identify the user

identify is the join between “an install touched my link” and “a real user did the valuable thing later.” It unlocks the conversion-attribution path — every conversion you fire afterwards resolves user_id → first_link_id via the install record so credit lands on the right campaign. Subscribers receive the full triple {user_id, link_id, link_metadata} in the webhook, so you can react (grant entitlements, credit referrals, send a welcome bonus) without a follow-up lookup.

The mobile SDK persists this binding locally, sends it to the server, and silently retries on the next app launch if the network call fails. One line, wherever you already handle your user session:

Bind the user

// Wherever you know the user is signed in
Task {
    try? await rift.setUserId("usr_abc123")
}

setUserId is idempotent — safe to call on every launch with the same user_id. On iOS, the SDK persists the binding in the Keychain, so the install_id survives app reinstalls.

Note: On logout: call rift.clearUserId() to remove the stored user binding. The install_id is preserved — only the user link is cleared.

The identify webhook payload your endpoint receives:

{
  "event": "identify",
  "timestamp": "2026-05-15T12:34:56Z",
  "data": {
    "tenant_id": "65f...",
    "user_id": "usr_abc123",
    "install_id": "device-uuid",
    "first_touch_link_id": "summer-sale",
    "first_touch_link_metadata": {
      "bonus_type": "welcome",
      "bonus_amount_usdc": "20"
    },
    "last_touch_link_id": "summer-sale",
    "timestamp": "2026-05-15T12:34:56Z"
  }
}

Note: Idempotent rebind (same install ↔ same user) is intentionally silent — the webhook only fires on a real state transition, so subscribers can't double-fulfill on SDK retries. For the existing-install re-attribution case (already-signed-in user clicks a new campaign link), credits flow through the attribute webhook instead — its payload carries the already-bound user_id.

Track conversions

convert is the last verb in the funnel — the valuable action you actually care about (first purchase, completed signup, subscription start). Fire it from your app with a stable idempotency_key and Rift resolves the user back to the campaign that drove their install via the installs record.

Fire a conversion

try await rift.trackConversion(
    conversionType: "first_trade",
    idempotencyKey: order.id,
    metadata: ["volume_usdc": "1500"]
)

Note: Server-to-server conversion sources (Stripe, RevenueCat, custom webhooks) configure separately so you can fire conversions from billing infrastructure that never touches the SDK. See Conversions.

Analytics

Funnel stats

Get the full funnel for a link — clicks, installs, identifies, and conversions keyed by type. Pass one or more comma-separated link IDs. The credit param defaults to last_touch (also supports first_touch and touched):

curl "https://api.riftl.ink/v1/analytics/stats?link_ids=summer-sale" \
  -H "Authorization: Bearer rl_live_YOUR_KEY"

{
  "from": "2026-04-25T00:00:00Z",
  "to": "2026-05-25T00:00:00Z",
  "link_ids": ["summer-sale"],
  "credit": "last_touch",
  "funnel": {
    "clicks": 1234,
    "new_users": { "installed": 89, "identified": 73 },
    "returning_users": { "reinstalled": 0, "new_device": 0, "engaged": 0 },
    "conversions": { "deposit": 19, "signup": 42 }
  }
}

Next: track conversions

Click and install attribution tell you who came from which link. To measure what they do next — signups, purchases, deposits — use Conversions. Track events from the mobile SDK with one line, or POST from your backend via webhooks. Either way, Rift attributes each conversion back to the originating link.