Android SDK Integration

This guide covers every feature and integration available in the Kubesense Android SDK (v2.1.0): adding dependencies, initializing the core SDK, and enabling RUM, distributed tracing, session replay, NDK crash reporting, profiling, WebView tracking, and feature flags — plus the supported third-party integrations (OkHttp, Jetpack Compose, image loaders, Apollo, Cronet, coroutines, RxJava, SQLDelight, and more).

Field	Value
Min SDK	23 (Android 6.0) — auto-instrumented integrations require minSdk 29
Target / Compile SDK	36
Language	Java 11 source/target compatibility, Kotlin
Distribution	Maven Central, group `ai.kubesense`

Core Setup

1. Configure repositories

Ensure Maven Central and Google's Maven repository are available in your project-level settings.gradle.kts:

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

note: The SDK is published to Maven Central under the ai.kubesense group. No custom Maven repository is required.

2. Add the core dependency

// module-level build.gradle.kts
dependencies {
    implementation("ai.kubesense:kubesense-android-core:2.1.0")
}

3. Initialize the SDK

Call Kubesense.initialize() in Application.onCreate() before enabling any feature:

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

        val configuration = Configuration.Builder(
            clientToken = "<CLIENT_TOKEN>",
            env = "production",
            variant = BuildConfig.VERSION_NAME
        )
            // Single intake host for every feature. Host only — no scheme, no path.
            .useKubesenseRumEndpoint("<your-collector-host>")
            .setFirstPartyHosts(listOf("api.example.com"))
            .build()

        Kubesense.initialize(this, configuration, TrackingConsent.GRANTED)
    }
}

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

warning: Changed in 2.1.0 — one endpoint for every feature. The per-feature useCustomEndpoint(...) builders have been removed. Point the SDK at your collector once, on the core Configuration.Builder, with useKubesenseRumEndpoint(...); RUM, Logs, Traces, Session Replay, Profiling, and Flags all upload through it.

The value is a host, with an optional port — intake.example.com or intake.example.com:8443. Any scheme or path you include is stripped: uploads always go over HTTPS to https://<host>/rum/api/v1/.... This is the opposite of the old per-feature setters, which took a full URL and appended nothing to it. Upgrading from 2.0.0? See Migrating from 2.0.0.

Omit useKubesenseRumEndpoint(...) to upload to the site selected with useSite(...) — KubesenseSite.PROD (us2.kubesense.ai) by default.

Remote Configuration

info: New in 2.1.0, and enabled by default. Applications write no remote-configuration code — Kubesense.initialize() does all of it.

Sampling rates, feature switches, and privacy masking can be managed centrally and delivered to the SDK, so you can retune or switch off a feature fleet-wide without shipping an app release.

How it works

Launch N                                  Launch N+1
────────────────────────────────          ────────────────────────────
1. read cached config (local, ~1ms)       1. read cached config  ← new values
2. init SDK with cached-or-default        2. init SDK with them
3. app runs with the current config
4. async fetch of the config document
5. cache the response for next launch

Kubesense.initialize() reads the document cached by the previous launch — a small local file read, never a network call — and applies its core settings before the upload pipeline starts.
Each X.enable() skips the feature if it is switched off remotely, then applies its own settings over what your code passed.
A fresh document is fetched on a background thread using an un-instrumented HTTP client, so the config request never shows up as a RUM resource or span.
The fetch repeats on an interval, so long-running kiosk-style apps still converge.

warning: SDK configuration is frozen at enable() time by design, so changes apply at the next launch, not mid-session.

Opting out or retuning

Configuration.Builder(clientToken, env, variant)
    .setRemoteConfigurationEnabled(false)                  // stay on in-code settings only
    .setRemoteConfigurationRefreshPeriodMs(6 * 3600_000L)  // default; <= 0 fetches once
    .build()

Values below one minute are raised to one minute. A value of zero or less fetches once after initialization and never again.

Defaults always win

A broken or missing configuration can never take your app away from safe SDK defaults:

Absent values change nothing. The document is an override layer, not a second source of defaults — a missing key leaves the setting exactly as your code built it.
Bad values are dropped individually. A value resolves to "absent" when it has the wrong JSON type, names an unknown enum constant, or is out of range (sample rates outside 0..100, sizes and counts <= 0). A completely malformed payload falls back to pure defaults, and unknown keys are ignored, so the format is forward-compatible.
Network problems are non-events. An HTTP failure, timeout, or unreadable body leaves the existing cache untouched. Responses are parse-validated before overwriting the cache, and the cache is written via a temp file and rename.
First launch and offline launches run on pure SDK defaults.

What can be controlled

Section	Settings
`features`	Switch `rum`, `logs`, `trace`, `sessionReplay`, or `profiling` off entirely — `enable()` returns without registering the feature, so your code needs no branch of its own. Only an explicit `false` disables.
`rum`	`sessionSampleRate`, `telemetrySampleRate`, `trackUserInteractions`, `trackFrustrations`, `trackNonFatalAnrs`, `trackBackgroundEvents`, `trackAnonymousUser`, `collectAccessibility`, `vitalsUpdateFrequency`, `longTaskThresholdMs`
`sessionReplay`	`sampleRate`, `startRecordingImmediately`, `imagePrivacy`, `touchPrivacy`, `textAndInputPrivacy`, `dynamicOptimizationEnabled`, `minRAMSizeMb`, `minCPUCoreNumber`
`logs`	`networkInfoEnabled`, `logcatLogsEnabled`, `bundleWithRumEnabled`, `bundleWithTraceEnabled` — applied in `Logger.Builder.build()`, so every logger picks them up
`trace`	`networkInfoEnabled`
`flags`	`trackExposures`, `rumIntegrationEnabled`
`profiling`	`launchSampleRate`
`core`	`batchSize`, `uploadFrequency`

Session Replay privacy values are applied after any app-local privacy logic, so masking can always be tightened centrally.

Features

Real User Monitoring (RUM)

Track user sessions, screen views, interactions, errors, network resources, and long tasks.

Setter	Values
`setImagePrivacy(...)`	`MASK_NONE`, `MASK_LARGE_ONLY`, `MASK_ALL`
`setTextAndInputPrivacy(...)`	`MASK_SENSITIVE_INPUTS`, `MASK_ALL_INPUTS`, `MASK_ALL`
`setTouchPrivacy(...)`	`SHOW`, `HIDE`

	FlagsClient	OpenFeature Provider
API style	Kubesense-native, instance-based context	Vendor-neutral, global context
Type system	Kotlin-native types	OpenFeature `Value` types
Structured flags	Returns `JSONObject`	Returns `Value.Structure`
Best for	Full Kubesense integration	Vendor-neutral or multi-provider setups

Value	Behaviour
`GRANTED`	Data is collected and uploaded
`NOT_GRANTED`	Data is not collected; existing data is discarded
`PENDING`	Data is collected locally but not uploaded until consent is granted

Removed in 2.1.0	Replacement
`RumConfiguration.Builder.useCustomEndpoint(url)`	`Configuration.Builder.useKubesenseRumEndpoint(host)`
`LogsConfiguration.Builder.useCustomEndpoint(url)`	same
`TraceConfiguration.Builder.useCustomEndpoint(url)`	same
`SessionReplayConfiguration.Builder.useCustomEndpoint(url)`	same
`ProfilingConfiguration.Builder.useCustomEndpoint(url)`	same
`FlagsConfiguration.Builder.useCustomFlagEndpoint(url)`	same
`FlagsConfiguration.Builder.useCustomExposureEndpoint(url)`	same

Android SDK Integration

ON THIS PAGE