Tracker

interface Tracker

The main entry point for recording analytics events.

Obtain an instance via the Autograph builder function and provide it to your UI (e.g. through AutographProvider from the autograph-compose module).

track, screen, and identify are fire-and-forget and safe to call from any thread, including the main thread: stamping and its disk persistence run on an internal serial dispatcher, so they never block the caller. Events are still stamped in call order.

Properties are declared Map<String, JsonElement>, not JsonObject, and must stay that way. JsonObject is a subtype of that map, and Kotlin/Native hands a Swift dictionary into a Map subtype unchecked — the call then dies with SIGSEGV instead of raising anything catchable (#193). Narrow it with asJsonObject inside the implementation if you need a JsonObject.

A tracker implemented in Swift receives a nested object or array value as its JSON text (#299). Kotlin/Native cannot hand such a value to Swift as a JsonElement, and the call would crash, so every call Autograph makes on a Swift tracker replaces it first, and so does LocalTracker.current under AutographProvider; decode it with JSONSerialization, but only for a key you know carries a nested value, because nothing marks the text as encoded: a string value holding the same JSON text arrives identically. Other Kotlin code that calls a Swift tracker directly gets no such replacement, so keep nested values out of those calls.

Functions

Link copied to clipboard

This tracker as Kotlin code can safely call: itself when it is written in Kotlin, and otherwise a Kotlin tracker that forwards every call to it with deliverableTo applied.

Link copied to clipboard
open fun close()

Drains, then releases the resources held by this tracker (its internal stamping/delivery coroutine scope). Call when a tracker is being discarded and replaced, such as recreating it on logout — not needed for a tracker that lives for the app's lifetime.

Link copied to clipboard

Closes this tracker like Tracker.close, but suspends instead of blocking, waits until the shutdown has finished and returns its final result. That is the same exposure as Tracker.close, which also returns only when the shutdown is done: the drain is bounded by AutographConfig.closeDrainTimeoutMillis, but the Transport.flush after it is not, so a transport whose flush blocks holds this call for as long as it blocks (#305). The reason it has no timer of its own is not that the shutdown is bounded: a timer equal to the drain bound would race the shutdown (a drain ending just under the bound, plus a flush, would report a completed shutdown as timed out), and the result would not be deterministic. Use closeAndAwait with a timeout when you need to stop waiting.

suspend fun Tracker.closeAndAwait(timeoutMillis: Long): CloseResult

closeAndAwait with an explicit per-call timeoutMillis for the wait. It bounds this caller's wait only, and a value at or above the drain bound does not guarantee the final result; see AwaitableCloseTracker.closeAndAwait. Long.MAX_VALUE waits for the shutdown to finish, as the no-argument overload does.

Link copied to clipboard
open fun flush()

Asks the underlying transport to send any queued events now.

Link copied to clipboard
abstract fun identify(userId: String, traits: Map<String, JsonElement> = EmptyJsonObject)

Associates the current user with userId and optional traits.

Link copied to clipboard
open fun notifyBackground()

Signals that the app moved to the background. See notifyForeground.

Link copied to clipboard
open fun notifyForeground()

Signals that the app moved to the foreground. Drives session-timeout bookkeeping. Wired automatically when using AutographProvider from autograph-compose.

Link copied to clipboard
open fun reset()

Clears user identity and session state, e.g. on logout. It does not touch AutographConfig.defaultProperties: clear those alongside it if they described the old user.

Link copied to clipboard
abstract fun screen(name: String, properties: Map<String, JsonElement> = EmptyJsonObject)

Records a screen view.

Link copied to clipboard
abstract fun track(name: String, properties: Map<String, JsonElement> = EmptyJsonObject, target: String? = null)

Records a custom event with the given name and properties.