Android SDK

Resolve Android App Links, deferred journeys, and outcomes from Kotlin applications.

Choose this SDK when#

Use the Android SDK for native Kotlin applications where an Activity or application coordinator owns incoming intents and navigation.

Warning

com.locusvia:locusvia-android 0.1.3 is source-ready but is not published to Maven Central. Evaluate through mavenLocal from a reviewed checkout.

Choose another SDK when: React Native, Capacitor, Unity, or shared Kotlin code owns the link lifecycle. Integrate once at that owning shell.

Before you start#

JDK 17 and a Gradle 8 compatible Android project.
An HTTPS assetlinks.json containing the application package and release signing SHA-256 fingerprint.
A LocusVia App Platform ID, SDK key, and API origin from the same environment.

Note

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

1. Publish the reviewed source locally#

Build the reviewed Android module into your local Maven repository, then consume version 0.1.3 from mavenLocal.

bash

gradle -p ../locusvia/sdk/android publishToMavenLocal

2. Add the dependency#

Keep mavenLocal ahead of Maven Central until the official artifact is published.

kotlin

repositories { mavenLocal(); mavenCentral() }

dependencies {
    implementation("com.locusvia:locusvia-android:0.1.3")
}

3. Create the client#

Use one client with a public SDK key. Configure clipboard recovery only when the product explicitly accepts the user prompt and privacy tradeoff.

kotlin

val client = LocusViaClient(
    LocusViaConfig(
        appID = "REPLACE_WITH_APP_ID",
        apiKey = "REPLACE_WITH_SDK_KEY",
        baseUrl = "https://staging.locusvia.com",
        linkProcessingMode = LocusViaConfig.LinkProcessingMode.ALL,
        shouldUseClipboard = false,
    )
)

4. Process the intent once#

Pass the launch or runtime intent through the SDK at the Activity boundary, then navigate only from a resolved link.

kotlin

lifecycleScope.launch {
    val result = client.resolveShortLink(intent.data.toString())
    result.link?.pathname?.let(navController::navigate)
}

Verify the integration#

Fetch assetlinks.json and confirm the release package name and signing fingerprint exactly.
Run adb app-link verification, then open a public URL against the signed application package.
Test cold start, foreground intent delivery, and a no-match link without creating duplicate navigation.

Warning

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

Troubleshoot by symptom#

Maven dependency failsRun publishToMavenLocal on the reviewed source and confirm mavenLocal is configured before Maven Central.

Browser chooser appearsReverify App Links and correct the package name, signing fingerprint, HTTPS response, and redirect behavior.

App opens but route does notPass the complete intent URL once and inspect the resolved link before navigating.

Debug works, release failsAdd the release signing fingerprint to assetlinks.json and re-run app-link verification.

Next steps#

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