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
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.
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.
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.
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.
Signals that the app moved to the background. See notifyForeground.
Signals that the app moved to the foreground. Drives session-timeout bookkeeping. Wired automatically when using AutographProvider from autograph-compose.
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.