Android SDK API

Functions, options, parameters, return values, and propagation helpers for the Teml Kotlin SDK.

This is the public Kotlin API for the native Teml Android SDK (minSdk 24). Public calls never throw into the host application; calls before initialization are safe no-ops with a warning. I/O runs on background executors.

Use a project key with ingest:write and analytics:write. The native SDK does not record replay.

Initialize and stop

Teml.init(
    applicationContext,
    TemlOptions(
        apiKey = BuildConfig.TEML_API_KEY,
        environment = "production",
    ),
)

API	Parameters	Returns	Behavior
`Teml.init(context, options)`	Android `Context`; `TemlOptions`	`Unit`	Configures identity, sessions, durable event queue, error transport, crash/lifecycle handlers, and timers. Repeated calls are ignored.
`Teml.flush(completion?)`	optional callback	`Unit`	Starts an asynchronous event flush, then invokes completion.
`Teml.shutdown(completion?)`	optional callback	`Unit`	Stops workers/hooks, flushes, releases state, and permits a later `init`.

`TemlOptions`

Only apiKey is required. The resolver clamps invalid capacities and sampling values.

Option	Type/default	Purpose
`apiKey`	`String`; required	Key sent to error/event endpoints.
`endpoint`	`String`; `https://api.teml.io`	Base URL for `/v1/traces` and `/api/v1/capture`.
`environment`	`String`; `development`	Deployment environment resource value.
`release`	`String?`; real service version	Regression and symbol-artifact identifier.
`dist`	`String`; empty	Build/artifact discriminator.
`serviceName`	`String?`; application ID	`service.name`.
`serviceVersion`	`String`; app version name then `0.0.0`	`service.version`.
`flushAt`	`Int`; `20`	Event-count flush threshold.
`flushIntervalMs`	`Long`; `5000`	Periodic event flush; zero disables it.
`maxStackTraceFrames`	`Int`; `50`	Maximum frames per error.
`breadcrumbCapacity`	`Int`; `100`	Ring-buffer capacity.
`maxQueueSize`	`Int`; `10000`	Durable diagnostic-event queue cap.
`errorSampleRate`	`Double`; `1`	Non-fatal error sampling from 0–1.
`enableCrashReporting`	`Boolean`; `true`	Install the uncaught-exception handler.
`debug`	`Boolean`; `false`	Emit SDK diagnostics through Logcat.

Identity, accounts, and events

Method	Parameters	Returns	Behavior
`Teml.identify(distinctId, set?)`	stable ID; person properties	`Unit`	Links anonymous and known identity and queues identify.
`Teml.group(type, key, set?)`	account type/key; properties	`Unit`	Records membership and `$groupidentify`.
`Teml.capture(event, properties?)`	event; properties	`Unit`	Queues a diagnostic event with current identity/session/groups.
`Teml.screen(name, properties?)`	screen; properties	`Unit`	Queues `$screen` and `$screen_name`.
`Teml.reset()`	—	`Unit`	Logout: rotates anonymous identity/session and clears groups.
`Teml.getDistinctId()`	—	`String?`	Current known/anonymous ID, or null before initialization.
`Teml.getSessionId()`	—	`String?`	Durable current session ID without extending its idle window.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`Teml.captureError(throwable, options?)`	`Throwable`; optional `CaptureOptions`	`String`	Captures a caught error and returns its ID, or `""` before init.
`Teml.captureMessage(message, level, options?)`	message; level default `info`; options	`String`	Captures a message and returns its ID.
`Teml.addBreadcrumb(category, message, level, data?)`	fields; level default `info`	`Unit`	Adds context for a later error.
`Teml.setUser(user)`	`TemlUser`	`Unit`	Sets global error user context.
`Teml.clearUser()`	—	`Unit`	Clears global error user context.
`Teml.captureRawError(...)`	type, message, frame JSON, fatal, mechanism, tags	`String`	Bridge API for React Native/Flutter; native apps should use `captureError`.

CaptureOptions fields are tags, extra, optional user, optional level, and optional fingerprint. TemlUser fields are id, email, username, ipAddress, and segment. Breadcrumb levels are debug, info, warning, and error.

Fatal crashes and failed manual error sends are spooled for the next launch. Upload the matching R8/ProGuard mapping.txt for every release/dist.

Backend propagation

API	Parameters	Returns	Behavior
`Teml.propagationHeaders()`	—	`Map<String,String>`	Fresh traceparent plus identity baggage when available.
`TemlInterceptor()`	OkHttp interceptor	`Interceptor`	Applies trace/identity headers to every request made by that OkHttp client.
`TemlPropagation.apply(connection)`	`HttpURLConnection`	`Unit`	Applies headers before `connect()`.
`TemlPropagation.headers(distinctId)`	optional ID	header map	Pure header builder.
`newTraceparent()`	—	`String`	Creates a sampled W3C traceparent.
`baggageWithDistinctId(id, existing?)`	ID; baggage	`String`	Replaces the Teml member while preserving others.
`percentEncode(value)`	string	`String`	Encodes a baggage value.

Attach TemlInterceptor only to clients whose destinations you trust. Public-device baggage is correlation context, not authenticated proof of the user.