Skip to content
Optima docs
SDKsAndroid SDK

Installation

Android SDK v1.4.0 — Installation

Requirements

  • minSdk 24 (Android 7.0). Both library modules are built against compileSdk 37.2, but what your app needs is set by their AAR metadata:
    • optima-sdk alone: compileSdk 34+, AGP 8.1.1+.
    • optima-sdk-compose: compileSdk 37+ and AGP 9.1+ — Compose UI 1.12 and lifecycle-runtime-compose 2.11 require both, so any app on current Compose already meets them. CheckAarMetadata names the exact floor if yours is lower.
  • Kotlin 2.3+ (the SDK is compiled with Kotlin 2.4, and a Kotlin compiler reads metadata one minor version ahead of itself), JVM target 17. Both library modules are compiled with JavaVersion.VERSION_17.
  • No required third-party dependencies. The core module pulls in kotlinx-coroutines-android, androidx.lifecycle:lifecycle-process (for foreground/background detection) and androidx.annotation — nothing else. HTTP goes over HttpURLConnection, JSON over the platform's org.json. There is no OkHttp, no kotlinx-serialization, and no Firebase dependency anywhere in the SDK, including in push — see chapter 7 for why that's safe to say even though the SDK has a push API.
  • The Compose module additionally depends on Compose runtime/foundation/ material3, androidx.webkit (the isolated WebView the HTML renderer uses) and androidx.browser (Custom Tabs for outbound links). Skip it entirely if you're going to render content yourself — see chapter 5.

Repositories

Today, the SDK is published to your local Maven cache only:

git clone <this repo>
cd optima-android-sdk
JAVA_HOME=$HOME/jdk17 ANDROID_HOME=$HOME/android-sdk ./gradlew publishToMavenLocal

Add mavenLocal() to your app's repository list (settings.gradle.kts, inside dependencyResolutionManagement.repositories, listed before mavenCentral() so a locally-published snapshot wins over anything already on Central under the same coordinates):

dependencyResolutionManagement {
    repositories {
        mavenLocal()
        google()
        mavenCentral()
    }
}

Once the SDK ships to Maven Central, mavenLocal() stops being necessary and the same implementation(...) line below resolves straight from Central — no other change to your build.

Gradle coordinates

// app/build.gradle.kts
dependencies {
    implementation("com.optima.sdk:optima-sdk:1.0.1")

    // Optional: only if you use the Jetpack Compose renderers (OptimaHost, OptimaSlot, …)
    implementation("com.optima.sdk:optima-sdk-compose:1.0.1")
}

optima-sdk-compose already depends on optima-sdk (api(project(":optima-sdk")) in its own build script), so a Compose-using app needs only the one line — adding optima-sdk explicitly as well is harmless but redundant.

Manifest and permissions

optima-sdk's own AndroidManifest.xml declares exactly one permission:

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

This merges into your app's manifest automatically at build time (standard AAR manifest merging) — you do not need to declare it yourself, and the manifest merger will complain only if you have explicitly removed it with a tools:node="remove" override, which would silently turn every network call the SDK makes into a SecurityException caught by the SDK's own guard (see chapter 9) rather than a visible crash. No other permission is requested: no location, no advertising ID, no phone state. The device identifier the SDK uses (deviceId, chapter 3) is a UUID it mints and stores itself, never a hardware identifier.

R8 / ProGuard

Nothing to do, and nothing kept. optima-sdk ships a consumer rules file inside the AAR (consumer-rules.pro), and it is deliberately empty: the SDK uses no reflection, no dynamic class loading and no name-based serialization (JSON is built and read field-by-field through org.json), so R8 is free to rename and strip everything your app does not call.

Earlier builds shipped -keep class com.optima.sdk.** { public *; }. That was a habit rather than a requirement, and an expensive one: Kotlin's internal is public in bytecode, so the rule pinned the SDK's whole internal surface too and defeated shrinking of code no app can even reference. If you had copied it into your own proguard-rules.pro, you can delete it.

org.json itself needs no ProGuard note: it ships as part of the Android platform (android.jar), not as a library dependency, so R8 never touches it and there is nothing to keep or warn about.

Optional: Play Install Referrer

The SDK captures UTM/click-id parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid) from the launching Activity's deep-link URL automatically — no dependency, captured on every Activity resume under screenTracking = AUTO (see chapter 2).

The Play Install Referrer is the other source, and the SDK does not depend on it: the Play library is yours to add, and you hand the string over with one call. That keeps an optional Google dependency out of every consumer's dependency graph, and puts the client's lifecycle (it must be connected, queried and disconnected) where it belongs — in the app.

// app/build.gradle.kts
dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
}
// once, on first launch — e.g. guarded by a SharedPreferences flag of your own
val client = InstallReferrerClient.newBuilder(context).build()
client.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
            runCatching { Optima.instance.captureReferrer(client.installReferrer.installReferrer) }
        }
        client.endConnection()
    }
    override fun onInstallReferrerServiceDisconnected() {}
})

captureReferrer (chapter 3) is guarded like every other public call, and the newest capture wins and applies to one session, and a referrer string is applied once per install — so reading the referrer on every launch is harmless. Skip all of this if referrer-based attribution doesn't matter for your app; deep-link UTM capture keeps working either way.

Other known gaps and parked items are listed in TODO.md at the repo root.

Initializing the SDK

Call Optima.init once, as early as possible — Application.onCreate is the right place, before any Activity is created, so screenTracking = AUTO (chapter 2) catches the very first screen:

Optima.init may be called from any thread (for example an App Startup initializer on a worker); the process-lifecycle observer is registered on the main thread for you. Application.onCreate is still the recommended place, because AUTO screen tracking only sees Activities resumed after init.

// MyApplication.kt
package com.example.shop

import android.app.Application
import com.optima.sdk.Optima
import com.optima.sdk.OptimaConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Optima.init(
            this,
            OptimaConfig(key = "oek_shop_a1b2c3", endpoint = "https://edge.shop.example") {
                debug = BuildConfig.DEBUG
            },
        )
    }
}

Don't forget to point your manifest at it:

<application android:name=".MyApplication" ... >

key and endpoint come from your Optima console: Edge → SDK keys, where you create (or reuse) a key on the mobile platform — see chapter 2 for what that platform distinction controls server-side. Optima.init never throws: construction failures (a SharedPreferences or filesystem error, a bad Context cast) are caught, logged as Optima.init failed; SDK disabled at Log.e, and the SDK stays uninitialized rather than crashing your Application.onCreate — an analytics dependency going down must never take the host app with it. A second call to Optima.init is a no-op with a warning; the first configuration wins.

Verifying the install

Set debug = true and watch adb logcat for the optima tag:

adb logcat -s optima:V

On a successful init you'll see the SDK's Ready event fire internally (you can also observe it yourself, see chapter 3), and every subsequent track/screen call logs a debug line describing what was enqueued, what was flushed, and any server response. A 401/403 on the first flush almost always means the key is for the wrong platform or has been revoked — see chapter 9. Once you see a 200 from POST /edge/v1/track in the log, the install is complete and hits are landing.

On this page