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-sdkalone: compileSdk 34+, AGP 8.1.1+.optima-sdk-compose: compileSdk 37+ and AGP 9.1+ — Compose UI 1.12 andlifecycle-runtime-compose2.11 require both, so any app on current Compose already meets them.CheckAarMetadatanames 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) andandroidx.annotation— nothing else. HTTP goes overHttpURLConnection, JSON over the platform'sorg.json. There is no OkHttp, no kotlinx-serialization, and no Firebase dependency anywhere in the SDK, including inpush— 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) andandroidx.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 publishToMavenLocalAdd 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:VOn 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.