Android SDK

The Android SDK (com.tolinku.sdk) provides App Links handling, deferred deep linking, event tracking, referrals, and in-app messages for Android.

Installation

Add the dependency to your build.gradle.kts:

dependencies {
    implementation("com.tolinku:sdk:0.1.0")
}

Setup

Configure the SDK in your Application.onCreate():

import com.tolinku.sdk.Tolinku

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Tolinku.configure(
            apiKey = "tolk_pub_your_key",
            context = this  // enables lifecycle-aware auto-flushing
        )
    }
}

Optional parameters:

Tolinku.configure(
    apiKey = "tolk_pub_your_key",
    baseUrl = "https://your-app.tolinku.com",
    context = this,
    debug = true  // enables debug logging
)

Tip

Passing the Application context enables automatic event flushing when the app goes to the background via ActivityLifecycleCallbacks.

User identification

Tolinku.setUserId("user_123")

// Clear on logout
Tolinku.setUserId(null)

Event tracking

// In a coroutine scope:
Tolinku.track("custom.app_open")

Tolinku.track("custom.purchase", mapOf(
    "amount" to "29.99",
    "currency" to "USD"
))

// Force flush
Tolinku.analytics.flush()

For Java interop, use the callback-based wrappers:

Tolinku.analytics.trackAsync("custom.app_open", null, object : TolinkuCallback<Unit> {
    override fun onSuccess(result: Unit) { }
    override fun onError(error: TolinkuError) { }
})

Ecommerce tracking

Track purchases, cart activity, and product events via Tolinku.ecommerce:

Tolinku.setUserId("user_123")

// Track a purchase
Tolinku.ecommerce.purchase(
    transactionId = "order_456",
    revenue = BigDecimal("49.99"),
    currency = "USD",
    items = listOf(
        TolinkuItem(itemId = "sku_1", itemName = "T-Shirt", price = BigDecimal("24.99"), quantity = 2)
    )
)

// Track product views and cart events
Tolinku.ecommerce.viewItem(
    items = listOf(TolinkuItem(itemId = "sku_1", itemName = "T-Shirt"))
)
Tolinku.ecommerce.addToCart(
    items = listOf(TolinkuItem(itemId = "sku_1", quantity = 1))
)
Tolinku.ecommerce.beginCheckout()

// Search and ratings
Tolinku.ecommerce.search(searchTerm = "shoes")
Tolinku.ecommerce.rate(itemId = "sku_1", rating = 4.5, maxRating = 5.0)

// Force flush
Tolinku.ecommerce.flush()

Ecommerce events are batched (10 events or 5-second timer) and auto-flushed when the app goes to the background via ActivityLifecycleCallbacks. The SDK manages cart IDs automatically via SharedPreferences, clearing them after purchase. All money values use BigDecimal for precision.

Note

Ecommerce tracking requires a paid plan (Standard or above).

Handling App Links

Handle incoming App Links in your Activity:

class DeepLinkActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        intent.data?.let { uri ->
            val path = uri.path       // e.g. "/merchant/abc123"
            val token = uri.lastPathSegment
            // Navigate to the deep link destination
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        intent.data?.let { uri ->
            // Handle deep link when activity is already running
        }
    }
}

Add the intent filter to your AndroidManifest.xml:

<activity android:name=".DeepLinkActivity">
    <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="your-app.tolinku.com" />
    </intent-filter>
</activity>

Tip

You also need to configure your SHA-256 fingerprint and package name. See App Links (Android) for the full setup guide.

Deferred deep linking

Claim the original link destination after the user installs your app.

Token-based claiming (recommended)

When a user clicks a Tolinku link on Android, the platform appends a tolk_token parameter to the Play Store referrer string. After install, use Google’s Install Referrer API to extract it:

// 1. Add the Install Referrer dependency to build.gradle.kts:
// implementation("com.android.installreferrer:installreferrer:2.2")

// 2. Retrieve the referrer and extract the tolk_token
import android.net.Uri
import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerStateListener

val referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
            val referrer = referrerClient.installReferrer.installReferrer
            // referrer is e.g. "tolk_token=abc123"
            val params = Uri.parse("https://x?$referrer").getQueryParameter("tolk_token")
            if (params != null) {
                // 3. Claim the deferred link
                lifecycleScope.launch {
                    val link = Tolinku.deferred.claimByToken(params)
                    if (link != null) {
                        // Navigate to link.deepLinkPath
                    }
                }
            }
            referrerClient.endConnection()
        }
    }

    override fun onInstallReferrerServiceDisconnected() {}
})

Signal-based claiming (fallback)

If the Install Referrer API is unavailable (e.g. sideloaded apps), use signal-based matching:

val link = Tolinku.deferred.claimBySignals(
    appspaceId = "your_appspace_id",
    context = this
)

Signal-based claiming auto-collects timezone, language, and screen dimensions from the device.

Referrals

val referrals = Tolinku.referrals

// Create a referral code
val result = referrals.create(userId = "user_123", userName = "Jane")
println(result.referralCode)  // "ABC123"
println(result.referralUrl)   // "https://myapp.tolinku.com/ref/ABC123"

// Look up a referral
val info = referrals.get(code = "ABC123")

// Link a referred user (status stays pending until reward milestone is reached)
referrals.complete(code = "ABC123", referredUserId = "user_456")

// Update milestone (completes the referral if it matches the reward milestone)
referrals.milestone(code = "ABC123", milestone = "first_purchase")

// Claim reward (after granting it in your system)
referrals.claimReward(code = "ABC123")

// Get leaderboard
val leaders = referrals.leaderboard(limit = 10)

Tip

If you have ecommerce auto-completion enabled, you don’t need to call milestone() manually. Just track the purchase via Tolinku.ecommerce.purchase() and the server will auto-complete the referral.

In-app messages

// Show highest-priority message
Tolinku.messages.show(
    context = this,
    trigger = "on_open",
    onAction = { action -> /* Handle CTA URL */ },
    onDismiss = { /* Message dismissed */ }
)

Messages are rendered in a WebView dialog.

Shutdown

Tolinku.shutdown()

This flushes queued events, cancels pending requests, and releases resources.