BaxLinks/Kotlin SDK

Kotlin SDK

Create and manage deep links natively in your Android app

Installation

Add to your root settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Then in your module build.gradle.kts:

dependencies {
    implementation("com.github.baxcloud:android-links-sdk:1.0.0")
}

Device info (Android ID, device model, OS version) is collected automatically. Only requires INTERNET permission — no extra dependencies.

Quick Start

1. Initialize the SDK

1import com.baxcloud.links.BaxCloudLinksClient
2import com.baxcloud.links.BaxCloudLinksConfig
3
4val links = BaxCloudLinksClient(
5    context = applicationContext,
6    config  = BaxCloudLinksConfig(
7        projectId = "your-project-id",
8        apiKey    = "your-api-key",
9        debug     = true, // Enable SDK debug logs (disable in production)
10    )
11)

2. Create a Deep Link

iOS/Android store URLs are configured once in Dashboard → BaxLinks → Setup. You only pass link-specific data:

1// Inside a coroutine scope (viewModelScope, lifecycleScope, etc.)
2val link = links.createLink(CreateLinkOptions(
3    fallbackUrl  = "https://yourapp.com/invite?code=ABC123",
4    deepLinkPath = "/invite/ABC123",
5    deepLinkParams = mapOf("inviteCode" to "ABC123", "referrer" to "john"),
6    title        = "Join us on MyApp!"
7))
8
9// Short URL from project subdomain (e.g. https://xxxxx.baxcloud.link/abc123)
10println(link.shortUrl ?: link.slug)

3. Track Install (device info auto-collected via Android ID)

1// Device ID, model, OS, OS version collected automatically
2links.trackInstall(appVersion = "1.0.0")

4. Get Deferred Deep Link

1// On first launch — device fingerprint matched automatically
2val result = links.getDeferredLink()
3
4if (result.found && result.deepLinkPath != null) {
5    navigate(result.deepLinkPath!!, result.deepLinkParams)
6}

Debug Logging

Trace SDK activity during development

Set debug = true in the config to see detailed SDK activity in Logcat (tag: BaxCloudLinks). Disable in production.

D/BaxCloudLinks: BaxCloudLinks SDK initialized (project: abc123)
D/BaxCloudLinks: handleDeepLink: https://xxx.baxcloud.link/mTX4Jw (scheme=https)
D/BaxCloudLinks: resolveLink: mTX4Jw
D/BaxCloudLinks: GET .../v1/sdk/links/resolve/mTX4Jw → 200
D/BaxCloudLinks: handleDeepLink: resolved params={type=post, objectId=abc}

Builder API

Fluent interface for constructing link options

1val options = BaxLinkBuilder("https://yourapp.com/landing")
2    .setAlias("summer-promo")
3    .setTitle("Summer Sale — 50% Off!")
4    .setDeepLinkPath("/promo/summer2024")
5    .addDeepLinkParam("discount", "50")
6    .setMaxClicks(1000)
7    .build()
8
9val link = links.createLink(options)

Convenience Methods

Purpose-built methods for common use cases

1// Invitation link
2val inviteLink = links.createInvitationLink(
3    inviteCode  = "ABC123",
4    fallbackUrl = "https://yourapp.com/invite?code=ABC123",
5    inviterName = "John"
6)
7
8// Referral link
9val refLink = links.createReferralLink(
10    referralCode = "REF_JOHN_2024",
11    fallbackUrl  = "https://yourapp.com/signup?ref=REF_JOHN_2024",
12    referrerName = "John Doe"
13)
14
15// App install campaign link
16val installLink = links.createAppInstallLink(
17    fallbackUrl = "https://yourapp.com",
18    campaign    = "summer_2024",
19    source      = "instagram"
20)
21
22// Content sharing link
23val contentLink = links.createContentLink(
24    contentType = "post",
25    contentId   = "post-789",
26    fallbackUrl = "https://yourapp.com/post/post-789",
27    title       = "Check out this post!"
28)

Handling Incoming Links

Resolve short links and URI scheme links automatically

The SDK provides handleDeepLink(uri: Uri) which automatically detects HTTPS short links (App Links) and resolves them via the API, or extracts query parameters directly from URI scheme links. Returns Map<String, Any?>? or null.

1// In your MainActivity
2override fun onCreate(savedInstanceState: Bundle?) {
3    super.onCreate(savedInstanceState)
4    intent?.data?.let { uri ->
5        lifecycleScope.launch {
6            val params = links.handleDeepLink(uri)
7            if (params != null) {
8                val type = params["type"] as? String
9                val objectId = params["objectId"] as? String
10                // navigate based on type and objectId
11            }
12        }
13    }
14}
15
16override fun onNewIntent(intent: Intent) {
17    super.onNewIntent(intent)
18    intent.data?.let { uri ->
19        lifecycleScope.launch {
20            val params = links.handleDeepLink(uri)
21            if (params != null) {
22                navigate(params["type"] as? String,
23                         params["objectId"] as? String)
24            }
25        }
26    }
27}

You can also use the lower-level handleIncomingUri(uri) if you only need to parse the URI without API resolution.

Resolve a Short Link Manually

1val result = links.resolveLink("mTX4Jw")
2// JSONObject: { "found": true, "deepLinkPath": "/post/abc",
3//   "deepLinkParams": { "type": "post", "objectId": "abc" } }

Extract Slug from URI

1val slug = links.extractSlug(uri)
2// "mTX4Jw"

Event Tracking

Device info (Android ID, model, OS, version) is collected automatically — no manual deviceId needed

1// First launch — attributes install to a link click
2links.trackInstall(appVersion = "1.0.0")
3
4// Every app open
5links.trackOpen(appVersion = "1.0.0")
6
7// After signup
8links.trackSignup()
9
10// After a purchase
11links.trackPurchase(value = 29.99, eventData = mapOf("planId" to "pro"))
12
13// Custom event
14links.trackCustomEvent(eventName = "level_complete", eventValue = 5.0)

Event Types: installopenreinstallsignuppurchasecustom

Deferred Deep Linking

Navigate users to the right screen after install

Call getDeferredLink() on first launch. BaxCloud fingerprints the device IP and matches it to a recent link click (48-hour window).

1private suspend fun checkDeferredLink() {
2    val prefs = getSharedPreferences("bax_prefs", MODE_PRIVATE)
3    if (prefs.getBoolean("deferred_checked", false)) return
4    prefs.edit().putBoolean("deferred_checked", true).apply()
5
6    // Track install (device info auto-collected)
7    links.trackInstall(appVersion = "1.0.0")
8
9    // Check for deferred deep link
10    val result = links.getDeferredLink()
11    if (result.found && result.deepLinkPath != null) {
12        withContext(Dispatchers.Main) {
13            navigate(result.deepLinkPath!!, result.deepLinkParams)
14        }
15    }
16}

How it works: Device IP is matched to a recent click within 48 hours. Returns deepLinkPath + deepLinkParams.

Attribution & Install Tracking

Query attributed installs for referral rewards

1val result = links.getAttributedInstalls()
2println("Total: ${result.total}")
3
4result.data.forEach { install ->
5    println("${install.linkSlug} · ${install.os} · ${install.country}")
6}
7
8// Filter by link
9val linkInstalls = links.getAttributedInstalls(
10    linkId = "your-link-id",
11    page   = 1,
12    limit  = 20,
13)

Platform Setup

Required AndroidManifest.xml configuration. Get your subdomain from Dashboard → BaxLinks → Setup.

1. Add Internet Permission

<uses-permission android:name="android.permission.INTERNET" />

2. Configure Intent Filters

Inside your <activity> tag:

<!-- Custom URI Scheme (e.g. myapp://invite/ABC123) -->
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" android:host="*" />
</intent-filter>

<!-- App Links (HTTPS Universal Links) -->
<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="xxxxx.baxcloud.link" />
    <data android:scheme="https" android:host="yourdomain.com" />
</intent-filter>

Use android:host="*" (wildcard) on the custom URI scheme filter so all deep link paths like myapp://invite/ABC123 are matched correctly.

3. Digital Asset Links (for App Links verification)

Go to Dashboard → BaxLinks → Setup and add your SHA-256 fingerprint. BaxCloud automatically serves the assetlinks.json file.

API Reference

Link Management

createLink(options)Create a new deep link

getLink(linkId)Get a link by ID

listLinks(status?, search?, page?, limit?)List project links

updateLink(linkId, options)Update a link

deleteLink(linkId)Delete a link

pauseLink(id) / resumeLink(id) / archiveLink(id)Change link status

Event Tracking

trackInstall(appVersion?, linkSlug?)Track first install — auto device info

trackOpen(appVersion?, linkSlug?)Track app open — auto device info

trackSignup(linkSlug?, eventData?)Track signup

trackPurchase(value, linkSlug?, eventData?)Track purchase

trackCustomEvent(eventName, ...)Track custom event

Deep Linking & Attribution

handleDeepLink(uri) → Map<String, Any?>?Resolve any incoming URI — HTTPS short links via API, URI scheme directly

resolveLink(slug) → JSONObjectResolve a short link slug to deep link data via the API

extractSlug(uri) → String?Extract the slug from a short link URI

handleIncomingUri(uri) → BaxDeepLinkDataParse an incoming URI (no API call)

getDeferredLink()Retrieve deferred deep link (auto device ID)

getAttributedInstalls(linkId?, page?, limit?)Query attributed installs

getAppConfig()Get project config + shortLinkBase

getProjectStats()Project-wide link stats

getLinkAnalytics(linkId)Per-link click analytics