Kotlin Multiplatform SDK

Share link resolution and lifecycle analytics across Android, JVM, and iOS targets.

Choose this SDK when#

Use the Kotlin Multiplatform SDK when shared Kotlin code owns the LocusVia client and platform applications provide navigation around it.

Warning

Version 0.1.3 is source-only and is not published to Maven. JVM and iOS simulator compilation are proven; Android and signed-device proof remain pending.

Choose another SDK when: only Android needs the client or your iOS application is Swift-first. The dedicated native SDKs have a smaller toolchain surface.

Before you start#

A Kotlin Multiplatform project using a compatible Kotlin, Ktor, and serialization toolchain.
A reviewed checkout of the LocusVia source package.
Platform code that delivers the received URL and opens the resolved pathname.

Note

Use an environment-scoped public SDK key. Never embed a server, admin, or privileged credential in an app.

1. Include the source build#

Add the reviewed SDK build to settings.gradle.kts and depend on it from commonMain. Keep the checkout revision fixed in CI.

kotlin

// settings.gradle.kts
includeBuild("../locusvia/sdk/kotlin-multiplatform")

// shared/build.gradle.kts
commonMain.dependencies {
    implementation("com.locusvia:locusvia-kotlin-multiplatform:0.1.3")
}

2. Create the shared client#

Construct one client with credentials from the same environment. The default client selects the platform HTTP engine.

kotlin

val locusVia = LocusViaClient(
    LocusViaConfig(
        appID = "REPLACE_WITH_APP_ID",
        apiKey = "REPLACE_WITH_SDK_KEY",
        baseUrl = "https://staging.locusvia.com",
    ),
)

3. Resolve in shared code#

Call the suspend API from your shared coroutine scope, then hand the pathname to platform navigation. A missing link is a safe no-match.

kotlin

val result = locusVia.resolveShortLink(receivedUrl)
result.link?.pathname?.let(platformNavigator::openRoute)

4. Track lifecycle events deliberately#

Call lifecycle helpers at the real application boundary. first_open is an application signal, not proof of store installation.

kotlin

locusVia.trackFirstOpen(
    mapOf("eventId" to JsonPrimitive(stableEventId))
)

locusVia.trackRegistration(
    mapOf("eventId" to JsonPrimitive(stableEventId))
)

Verify the integration#

Run JVM common tests and compile the iOS simulator target on the exact source revision.
Compile the consuming Android and iOS applications, not only the SDK module.
Open a verified public link on each supported target and confirm platform navigation receives the same pathname.

Warning

A successful build proves source compatibility only. Test a real link on the target browser or signed device before release.

Troubleshoot by symptom#

Dependency cannot resolveConfirm includeBuild points to the SDK directory and the dependency coordinates match version 0.1.3.

iOS target does not compileAlign Kotlin, Ktor, and serialization versions and compile an explicit simulator target in CI.

Request throws LocusViaRequestExceptionInspect its status and response body, then verify app ID, SDK key, base URL, tenant, and environment.

Native app never receives the URLConfigure platform associations and URL delivery in the Android or iOS shell; the shared client cannot register them.

Next steps#

Confirm your domain associations, then add conversion and revenue events only after link resolution works end to end.