LimeLink Android SDK

Target SDK Version: 0.3.0 | Min SDK: 24 | Compile SDK: 35

LimeLink Android SDK provides App Link resolution, deferred deep links, and link event tracking through a single public facade.

View previous Android SDK releases

Requirements

Installation

Production SDK builds are distributed as verified, minified binaries through LimeLink's private GitHub Packages registry. Obtain repository read access and a classic GitHub PAT with read:packages, then store credentials outside your project in ~/.gradle/gradle.properties:

limelink.github.user=GITHUB_USERNAME
limelink.github.token=CLASSIC_PAT_WITH_READ_PACKAGES

Add the private Maven repository to settings.gradle.kts:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/hellovelop/limelink-aos-sdk-binary")
            credentials {
                username = providers.gradleProperty("limelink.github.user").orNull
                password = providers.gradleProperty("limelink.github.token").orNull
            }
        }
    }
}

Add the dependency:

dependencies {
    implementation("org.limelink:limelink_aos_sdk:0.3.0")
}

JitPack, source dependencies, Maven Local, debug artifacts, and composite builds are not supported consumer distribution channels.

Initialize the SDK

Initialize the SDK once in your Application:

import android.app.Application
import org.limelink.limelink_aos_sdk.LimeLinkSDK
import org.limelink.limelink_aos_sdk.config.LimeLinkConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = LimeLinkConfig.Builder("YOUR_API_KEY")
            .setLogging(BuildConfig.DEBUG)
            .setDeferredDeeplinkEnabled(true)
            .build()

        LimeLinkSDK.init(this, config)
    }
}

Register the application class in AndroidManifest.xml:

<application
    android:name=".MyApp"
    ... />

Configuration

Configure Android App Links

Add Internet permission and an App Link intent filter:

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

<application android:name=".MyApp">
    <activity
        android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTop">

        <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="*.limelink.org"
                android:pathPrefix="/link/" />
        </intent-filter>
    </activity>
</application>

LimeLink endpoints use HTTPS. The SDK does not require global cleartext traffic, so do not enable cleartextTrafficPermitted="true" for this integration.

Receive Link Results

Register a long-lived listener after initialization:

import android.content.Intent
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import org.limelink.limelink_aos_sdk.LimeLinkListener
import org.limelink.limelink_aos_sdk.LimeLinkSDK
import org.limelink.limelink_aos_sdk.response.LimeLinkError
import org.limelink.limelink_aos_sdk.response.LimeLinkResult

class MainActivity : ComponentActivity() {
    private val linkListener = object : LimeLinkListener {
        override fun onDeeplinkReceived(result: LimeLinkResult) {
            val destination = result.resolvedUri
            val isDeferred = result.isDeferred
            val query = result.queryParams

            // Route to destination in your app.
        }

        override fun onDeeplinkError(error: LimeLinkError) {
            Log.e("LimeLink", "[${error.code}] ${error.message}")
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        LimeLinkSDK.addLinkListener(linkListener)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
    }

    override fun onDestroy() {
        LimeLinkSDK.removeLinkListener(linkListener)
        super.onDestroy()
    }
}

Listener callbacks are delivered on the Android main thread. Lifecycle integration automatically handles normal Activity intents. If your host app also forwards an Intent explicitly, the SDK prevents the same Intent instance from being processed twice.

Result fields

Explicit Link Handling

Use the facade when your Activity needs to forward an Intent explicitly:

LimeLinkSDK.handleUniversalLink(this, intent)

Deferred Deep Links

For Android 0.3.0, the Play Store referrer contains a LimeLink-issued UUID. With deferred handling enabled, the SDK checks it automatically during initialization and resolves a valid result through the listener.

You can also request a fresh check explicitly:

LimeLinkSDK.handleDeferredDeepLink(this) { result, error ->
    when {
        result != null -> navigateTo(result.resolvedUri)
        error != null -> Log.e("LimeLink", error.message)
        else -> Unit // Normal no-result outcome.
    }
}

• Success returns a deferred LimeLinkResult.
• No matching referrer returns (null, null).
• Transport or protocol failures return LimeLinkError.
• A result completed before listener registration is retained and replayed once to the next listener.
• Raw referrer values and UUIDs are not part of the public result contract.

Manual Stats Tracking

Link handling tracks the normal event automatically. If you need to track the current Intent explicitly:

LimeLinkSDK.trackLinkStatus(this, intent)

Public API

Use the facade and public result/configuration models only. Install Referrer helpers, URL parsers, network services, request models, and SDK state are internal implementation details.

Migrating to 0.3.0

Version 0.3.0 removes deprecated compatibility APIs. Before upgrading:

• Replace JitPack or source installation with the private binary Maven package.
• Replace callback-based Universal Link handling with handleUniversalLink(activity, intent) and a listener.
• Replace suffix-based deferred calls with handleDeferredDeepLink(context, completion).
• Remove calls to checkDeferredDeeplink, getInstallReferrer, URL parser helpers, and isUniversalLink.
• Remove access to LimeLinkResult.referrerInfo.
• Recompile the consumer app against 0.3.0.

Troubleshooting

Package authentication fails

• 401: check username and PAT.
• 403: check repository access, read:packages, and organization SSO authorization.
• Keep credentials in the user Gradle properties file, not source control.

Links are not delivered

1. Confirm LimeLinkSDK.init() runs once.
2. Confirm the listener remains registered.
3. Verify the manifest intent filter and singleTop launch mode.
4. Verify the domain's Digital Asset Links configuration.
5. Enable SDK logging in a debug build.

Deferred links are not delivered

1. Confirm deferred handling is enabled.
2. Install through Google Play; sideloaded builds do not receive Play Install Referrer data.
3. Verify the backend-generated referrer value has not expired.
4. Treat a normal no-result as a valid outcome.