Skip to main content
Version: 1.1.x

Events - Get Started

An Event is a one-time capture — a point in time marked with a human-readable identifier and, optionally, a State snapshot. Use Events to capture discrete user actions (button taps, form submissions) or business metrics (purchase completed, payment failed) that don't need a continuous timeline like a State does.

Custom Event identifiers are separate from built-in SDK Events, including API requests.

Recording a basic Event​

Coryn.addEvent("UserProfileSaved")

Attaching State to an Event​

If the event requires additional context beyond what your State Providers are already capturing, pass a state argument:

import ai.coryn.replay.shared.state.CorynState
import kotlinx.serialization.json.Json
import kotlinx.serialization.Serializable

@Serializable
data class PaymentFailedState(
    val reason: String,
    val amount: Double
) : CorynState {
    override fun toJsonString(): String {
        return Json.encodeToString(serializer(), this)
    }
}

Coryn.addEvent(
    eventId = "PaymentFailed",
    state = PaymentFailedState(
        reason = "Insufficient funds",
        amount = 29.99
    )
)

Backdating an Event​

By default, the event is recorded at the moment Coryn.addEvent() is called. If the event actually occurred earlier — for example, it was processed asynchronously — pass timePassedMs to indicate how many milliseconds ago it happened:

Coryn.addEvent(
    eventId = "PaymentFailed",
    state = PaymentFailedState(
        reason = "Insufficient funds",
        amount = 29.99
    ),
    timePassedMs = 350L
)

Negative timePassedMs values are treated as zero. The resulting timestamp is clamped between the start of the recorded session and the current elapsed session time.

Thread safety​

All Coryn.addEvent() overloads are thread-safe and can be called from any thread. An attached State is serialised asynchronously: pass a stable snapshot, do not mutate it after the call, and return valid JSON from its serializer.

Aggregate high-frequency data into a State Provider instead of emitting an Event for every update. Submitting Events faster than they can be recorded can cancel recording.

Keep State size reasonable

States and Events share an approximate 200 KB budget per 15-second recording segment, excluding UI captures. Exceeding this budget can omit Events until the next segment. Keep payloads small; see State size guidance.

  • API Requests — predefined request Events, with manual reporting and an optional OkHttp interceptor
  • States — continuous context tracked over the session timeline
  • Screens — screen-level navigation markers