Mobile SDK

Android SDK

Native Kotlin SDK for deep linking, attribution, user binding, and conversion tracking. Built with Rust and compiled to a Kotlin library via UniFFI.

Quick Start

Add the library

Download the latest rift-android-sdk-*.tar.gz from GitHub Releases. Extract into your project and add it as a module:

// settings.gradle.kts
include(":rift-sdk")
project(":rift-sdk").projectDir = file("libs/android")

// app/build.gradle.kts
dependencies {
    implementation(project(":rift-sdk"))
}

Initialize (one line)

You need a publishable key. The convenience constructor auto-wires SharedPreferences storage and reads the app version from PackageManager.

import ink.riftl.sdk.*

// One line — SharedPreferences storage, app version, all defaults.
val rift = RiftSdk.create("pk_live_YOUR_KEY", applicationContext)

Note: The SDK generates a persistent install_id (UUID) on first launch and stores it in SharedPreferences. On Android, app data is wiped on uninstall — the install ID does not survive reinstallation. For fresh-install attribution, use the Google Play Install Referrer.

Bind the user (one line)

Call setUserId wherever you handle your user session. Safe to call on every launch. The SDK handles persistence, sync, and retry.

// Wherever you know the user is signed in:
lifecycleScope.launch {
    runCatching { rift.setUserId(userId = currentUser.id) }
}

Track conversions (one line)

Fire a conversion event whenever a user does something worth counting. The SDK reads the bound user_id and POSTs to the Rift API using your publishable key.

// On trade completion, purchase, signup — whatever you're measuring:
rift.trackConversion(
    conversionType = "trade",
    idempotencyKey = orderId,
    metadata = mapOf("asset" to "ETH", "side" to "buy")
)

Suspend function — call from a coroutine scope. The server dedupes via idempotencyKey, so retries are safe.

Deferred Deep Linking

Read link ID from install referrer

When a user clicks a Rift link on Android, the link ID is appended to the Play Store URL. Read it and resolve the link after install:

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() {}
    })
}

Click Tracking

Record a click

If your app opens Rift links internally, record the click:

val result = rift.click(linkId = "summer-sale")
Log.d("Rift", "Platform: ${result.platform}")
Log.d("Rift", "Deep link: ${result.androidDeepLink}")

Logout

Call clearUserId() when the user signs out. The install ID is preserved.

rift.clearUserId()

API Reference

Constructors

Constructor	Description
RiftSdk.create(publishableKey, context)	Convenience. Auto-wires SharedPreferences storage + app version. Recommended.
RiftSdk(config, storage)	Full control. Pass custom `RiftConfig` and `RiftStorage` implementation.

Methods

Method	Returns	Description
setUserId(userId)	Unit (suspend @Throws)	Bind the install to a user. Persists + syncs + retries on next launch.
trackConversion(conversionType, idempotencyKey, metadata?)	Unit (suspend @Throws)	Fire a conversion event. POSTs to the Rift API via publishable key.
checkDeferredDeepLink(clipboardText)	DeferredDeepLinkResult? (suspend @Throws)	One-call deferred deep link: parse, attribute, fetch link data.
clearUserId()	Unit (@Throws)	Remove stored user binding. Call on logout.
installId()	String (@Throws)	Persistent install UUID. Generates on first call.
reportAttributionForLink(linkId)	Boolean (suspend @Throws)	Simplified attribution — uses internal install_id + app version.
click(linkId)	ClickResult (suspend @Throws)	Record a click and return link data.
getLink(linkId)	GetLinkResult (suspend @Throws)	Fetch link data without recording a click.

Free functions

Function	Description
parseReferrerLink(referrer)	Extracts link ID from `rift_link=<link_id>` referrer string. Returns `null` if not found.