eventtracker/in.singhangad.eventtracker/EventTracker

EventTracker

EventTracker is the single entry point for the EventTracker Android library.

The library captures events in the host app, persists them to a local database, and dispatches them to one or more configured in.singhangad.eventtracker.adapter.EventAdapter destinations. Network destinations use batched delivery with retry and dead-letter handling.

Initialization must happen exactly once per process, typically in Application.onCreate. After initialization, all calls are safe from any thread.

EventTracker.initialize(
    context = applicationContext,
    config = EventTrackerConfig.Builder()
        .addAdapter(BackendBatchAdapter(endpoint = "https://api.example.com/v1/events"))
        .addAdapter(FirebaseAdapter()) // requires :eventtracker-adapter-firebase
        .batchSize(50)
        .batchIntervalMs(30_000)
        .maxRetries(8)
        .build()
)

EventTracker.track("checkout_started", mapOf("cart_size" to 3))

Since

1.0.0

Functions

deadLetterSize

suspend fun deadLetterSize(): Long

Number of events currently in the dead-letter queue.

diagnostics

fun diagnostics(): Diagnostics

Snapshot of internal counters for observability. Values are monotonically increasing within a process lifetime and reset to zero on process start.

flush

fun flush(): Job

Force an immediate flush of all queued backend events, bypassing batch-size and batch-interval triggers. The returned Job completes when the flush attempt finishes.

identify

fun identify(userId: String?, traits: Map<String, Any?> = emptyMap())

Associate a stable user identifier and optional user traits with the current session. Subsequent events will carry this user id until reset is called.

initialize

fun initialize(context: Context, config: EventTrackerConfig)

Initialize the library. Safe to call multiple times; subsequent calls are no-ops and log a warning. Must be called before any track or identify call.

purgeDeadLetters

suspend fun purgeDeadLetters()

Permanently delete all DLQ entries.

replayDeadLetters

suspend fun replayDeadLetters(limit: Int = 500): Int

Move up to limit DLQ rows back into the live queue, with attempt_count reset to zero. Useful after a backend fix.

reset

fun reset()

Forget the current user and start a new anonymous session. Does not clear queued events; those continue to be delivered with the user id they were tracked under.

setOptOut

fun setOptOut(optedOut: Boolean)

Set the opt-out flag. When true, all subsequent track and identify calls are dropped silently. Already-persisted events are NOT deleted unless wipeLocalData is also called.

track

fun track(name: String, properties: Map<String, Any?> = emptyMap(), destinations: Set<String>? = null)

Track an event. Returns immediately; persistence and delivery happen on a background dispatcher.

wipeLocalData

fun wipeLocalData(): Job

Delete all locally persisted events, including the dead-letter queue. Intended for GDPR / opt-out compliance and QA reset. Does not affect events already delivered to destinations.

EventTracker

Since

See also

Functions