Deep Linking

Deferred Deep Linking

Route users to specific content even if they didn't have the app installed when they clicked. Rift passes the link URL through the install flow and delivers it to the app after install.

How it works

User clicks a Rift link on mobile (via web SDK or landing page)
iOS: the full link URL is copied to the clipboard (e.g. https://go.yourcompany.com/summer-sale)
Android: the link ID is appended to the Play Store URL as referrer=rift_link%3Dsummer-sale in the install referrer
User installs the app and opens it
App reads the clipboard (iOS) or install referrer (Android) to get the link URL/ID
App extracts the link ID and calls GET /r/{link_id} with Accept: application/json to get link data
App calls POST /v1/lifecycle/attribute to record the attribution
App routes user to the deep link destination

iOS — SDK (recommended)

The SDK does everything in one call: parses the clipboard, reports attribution, and returns the link data for navigation.

// On first launch
if let result = try await rift.checkDeferredDeepLink(
    clipboardText: UIPasteboard.general.string
) {
    UIPasteboard.general.string = ""  // clear after reading
    if let deepLink = result.iosDeepLink {
        handleDeepLink(deepLink)
    }
}

Note: The caller reads the clipboard explicitly because iOS 16+ shows a paste permission dialog. The SDK does NOT read the clipboard itself — your app controls when that dialog appears.

Android — SDK (recommended)

On Android, use the install referrer to get the link ID, then resolve and attribute:

import com.android.installreferrer.api.*

fun checkDeferredDeepLink() {
    val client = InstallReferrerClient.newBuilder(this).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(code: Int) {
            if (code == InstallReferrerResponse.OK) {
                val referrer = client.installReferrer.installReferrer
                val linkId = parseReferrerLink(referrer)
                if (linkId != null) {
                    lifecycleScope.launch {
                        rift.reportAttributionForLink(linkId = linkId)
                        val link = rift.getLink(linkId = linkId)
                        link.androidDeepLink?.let { handleDeepLink(it) }
                    }
                }
            }
            client.endConnection()
        }
        override fun onInstallReferrerServiceDisconnected() {}
    })
}

Resolve a link (API)

To get the link data for routing, send a JSON request to the public resolve endpoint:

curl https://api.riftl.ink/r/summer-sale \
  -H "Accept: application/json"

Response:

{
  "link_id": "summer-sale",
  "ios_deep_link": "myapp://promo/summer-sale",
  "android_deep_link": "myapp://promo/summer-sale",
  "web_url": "https://example.com/promo/summer-sale",
  "social_preview": { "title": "Summer Sale — 50% Off" },
  "agent_context": {
    "action": "purchase",
    "cta": "Get 50% Off"
  },
  "_rift_meta": {
    "status": "active",
    "tenant_domain": "go.yourcompany.com",
    "tenant_verified": true
  }
}