Android SDK API

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

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

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

Initialize and stop

Anectico.init(
    applicationContext,
    AnecticoOptions(
        apiKey = BuildConfig.ANECTICO_API_KEY,
        environment = "production",
    ),
)

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

`AnecticoOptions`

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.anectico.com`	Base URL for `/v1/traces`, `/v1/logs`, 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`	Independent event/log count flush threshold.
`flushIntervalMs`	`Long`; `5000`	Foreground-only periodic event/log flush; zero disables it.
`maxStackTraceFrames`	`Int`; `50`	Maximum frames per error.
`breadcrumbCapacity`	`Int`; `100`	Ring-buffer capacity.
`maxQueueSize`	`Int`; `10000`	Per-queue cap: up to this many durable events and independently this many durable logs.
`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
`Anectico.identify(distinctId, set?)`	stable ID; person properties	`Unit`	Links anonymous and known identity and queues identify.
`Anectico.group(type, key, set?)`	account type/key; properties	`Unit`	Records membership and `$groupidentify`.
`Anectico.capture(event, properties?)`	event; properties	`Unit`	Queues a diagnostic event with current identity/session/groups.
`Anectico.screen(name, properties?)`	screen; properties	`Unit`	Queues `$screen` and `$screen_name`.
`Anectico.reset()`	—	`Unit`	Logout: rotates anonymous identity/session and clears groups, global error-user context, and breadcrumbs.
`Anectico.getDistinctId()`	—	`String?`	Current known/anonymous ID, or null before initialization.
`Anectico.getSessionId()`	—	`String?`	Durable current session ID without extending its idle window.

Logs

Method	Parameters	Returns	Behavior
`Anectico.captureLog(body, severity, attributes?)`	nonblank body; severity default `info`; attributes	`String`	Atomically queues an OTLP log and returns its stable 32-hex `anectico.log.id`, or `""` before init/for invalid or oversized input/if durable persistence fails.

Severity accepts trace, debug, info, warn/warning, error, and fatal. Caller attribute values are sanitized and stringified. Each occurrence snapshots its original time, identity, non-activity session, groups, release/dist, app/build, device, service, and environment. Retry after offline use or process recreation retains that snapshot and preserves oldest-first order.

The log spool is independently bounded to maxQueueSize records and 10 MiB, dropping oldest; one record is capped at 1 MiB. It flushes at flushAt, periodically, on background, flush, shutdown, and next initialization. Network/429/5xx responses retry; 2xx acknowledges; other 4xx drops. Android is currently the only native mobile SDK with this public log API; iOS and RN/Flutter bridges do not yet expose it.

The SDK-owned $app_opened lifecycle event carries the resolved release, app version/build, platform, OS, and privacy-safe device family. One event is emitted per real foreground transition. Backgrounding emits one $app_backgrounded, stops recurring flushes before one explicit event/log flush, and the next foreground recreates exactly one timer without rotating the session by itself. These properties cannot be overridden and contain no installation/device identifier. Anectico uses the marker to count canonical-person release adoption and the adopted-person error-free rate.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`Anectico.captureError(throwable, options?)`	`Throwable`; optional `CaptureOptions`	`String`	Captures a caught, handled `error` with mechanism `java.caught_exception` and returns its ID, or `""` before init.
`Anectico.captureMessage(message, level, options?)`	message; level default `info`; options	`String`	Captures a message and returns its ID.
`Anectico.addBreadcrumb(category, message, level, data?)`	fields; level default `info`	`Unit`	Adds context for a later error.
`Anectico.setUser(user)`	`AnecticoUser`	`Unit`	Sets global error user context.
`Anectico.clearUser()`	—	`Unit`	Clears global error user context.
`Anectico.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. AnecticoUser 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. The crash handler marks uncaught throwables as unhandled fatal errors with mechanism java.uncaught_exception. Native level, handling, and mechanism values are SDK-owned; caller tags cannot override them.

Each occurrence automatically includes release/distribution, Anectico SDK/platform, Android model and OS version, and app version/build. These fields are SDK-owned so Issue Story receives trustworthy device context. Anectico records the shared hardware model, not a physical-device identifier: Android ID, serial number, installation ID, and the user-assigned device name are never collected.

Backend propagation

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

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