Android SDK (Kotlin)

Module: sdks/android (library se.hellsoft.vaka:vaka-android, plus the Gradle plugin se.hellsoft.vaka for R8 mapping upload). Step-by-step setup: install/android.md.

API

// Application.onCreate
Vaka.init(this, VakaConfig(
    key = "vk_...",
    endpoint = "https://vaka.example.com",
    release = BuildConfig.VERSION_NAME,
    environment = if (BuildConfig.DEBUG) "debug" else "production",
))

Vaka.screen("Checkout")                          // screen_view; automatic for Activities by default
Vaka.track("purchase", mapOf("plan" to "pro"))   // custom event
Vaka.captureException(e)                          // handled exception; returns the event id
Vaka.captureMessage("Slow payment", VakaLevel.WARNING)
Vaka.addBreadcrumb("cart", "Added item 42")
Vaka.setTag("flavor", "free")                     // tag on later errors; null removes it
Vaka.identify("user-123")                         // opt-in user id; Vaka.identify(null) clears it
Vaka.flush()                                      // send the queue now

All methods are no-ops before init and safe from any thread. Java callers use the same static methods.

VakaConfig

Field	Default
`key`, `endpoint`, `release`	required	`release` must match the mapping upload (`versionName` by default)
`environment`	`production`
`inAppPackages`	app package name	frames from these packages, and any non-framework class (R8-renamed included), are `in_app`
`autoScreenViews`	`true`	`screen_view` per resumed Activity, named after its class
`autoBreadcrumbs`	`true`	Activity lifecycle and connectivity
`captureUncaughtExceptions`	`true`
`sessionTracking`	`true`
`flushIntervalMillis` / `maxBatchSize`	10 000 / 50
`maxQueueSize`	1000	oldest items dropped beyond this
`sessionTimeoutMillis`	30 000	background time that ends a session
`tags`	empty	tags on every error
`enabled`	`true`	`false` makes the SDK a no-op
`debug`	`false`	log to Logcat, tag `Vaka`

Behaviour

Uncaught JVM exceptions: a Thread.UncaughtExceptionHandler writes the error and a crashed session update to disk synchronously, then calls the previous handler. Both are sent on next launch.
Sessions: start when the first Activity starts (foreground), end after 30 s in the background as exited, or errored if handled errors were reported. A session left open by a process that died in the foreground is reported as abnormal on the next launch; one that died in the background is closed as exited/errored. Foreground detection counts started Activities, the same signal as ProcessLifecycleOwner, so no androidx dependency is needed.
Automatic breadcrumbs: Activity lifecycle, network connectivity changes (API 24+).
Offline queue on disk (one file per item in filesDir/vaka/queue), batched sends every 10 s or 50 items, gzip, exponential backoff up to 5 min on 429/5xx and network errors, batch splitting on 413, sending paused until restart on 401.
anon_id: random UUID stored in app-private SharedPreferences (se.hellsoft.vaka), as is the identify user id.
No dependencies beyond the Android SDK and Kotlin stdlib (HttpURLConnection, hand-written JSON).
minSdk 21.

Gradle plugin

id("se.hellsoft.vaka") registers uploadVakaMapping<Variant> for each minified application variant and runs it after minify<Variant>WithR8. It POSTs the mapping to /api/v1/projects/{project}/artifacts (kind=proguard, release=versionName).

vaka {
    url.set("https://vaka.example.com")   // or VAKA_URL / -Pvaka.url
    project.set("my-app")                 // or VAKA_PROJECT / -Pvaka.project
    token.set(...)                        // default: VAKA_TOKEN / -Pvaka.token (API token, write scope)
    release.set("2.3.1")                  // default: the variant's versionName
    uploadMapping.set(false)              // or VAKA_UPLOAD_MAPPING=false, to skip
    failOnError.set(true)                 // default false: a failed upload only logs a warning
}

See ingest.md for the wire format.