Capture analytics

The SDK captures product events and sends them to Voidhash for you. Every event is attributed to the current person and delivered in background batches. You do not need a separate analytics package.

Capture an event

Call capture with an event name and any properties you want to attach:

voidhash.client.capture("upgrade_button_clicked", {
  source: "settings",
  plan: "monthly",
});

capture() is synchronous. It queues the event and returns immediately. This is true even while the provider is still initializing, so you can capture events from your first render.

Property values are copied when you call capture(), so changing the object afterwards does not change the event. Values JSON cannot hold are converted: a bigint is sent as a decimal string, a Date as an ISO string and NaN or Infinity as null. Functions, undefined and circular references are left out. An event with more than 10,000 property values is dropped and reported through onDiagnostic as ANALYTICS_EVENT_DROPPED, so pass the fields you need rather than whole framework objects such as press events.

Each event also records the app version, OS version and locale at the moment you capture it. An event that waits offline across an app update still reports the version it happened in.

Use clear, stable event names. Names that begin with $ are reserved for Voidhash's own events.

Automatic events

The SDK records common lifecycle events for you, so you do not need to capture them yourself:

$app_installed
$app_updated
$app_opened
$app_backgrounded
$app_became_active
$sign_out
$screen, see Track screens

$app_opened marks a launch the customer sees. When the system starts your app in the background, for example for a silent push or a background fetch, the SDK records nothing for the launch itself and records $app_opened (with $app_installed or $app_updated for a new release) when the customer first opens the app, instead of $app_became_active.

Sessions

Every event carries a session id, so screen paths and funnels can tell one visit from the next. A session starts with the first event and ends after 30 minutes without any event, including time spent in the background. The next event then opens a new session. Signing out also starts a new session, and the session survives app restarts within the same 30 minutes. Read the current id when you need to correlate your own data with it:

const sessionId = voidhash.client.getSessionId();

Flush before a boundary

Events flush automatically in batches. A batch is sent when it reaches 20 events or every 5 seconds, whichever comes first, and failed requests are retried with exponential backoff (each retry waits longer than the last). Force delivery when the app is about to cross an important boundary, such as a screen the customer may not return from:

await voidhash.client.flush();

You do not need to flush around identity changes. The identity methods flush at the correct time on their own, so events captured before identify() or signOut() stay attached to the previous identity.

Update customer traits

Trait updates are not analytics events. They go to the customer's profile through a queue of their own that is never trimmed to make room for events. See Set customer attributes for how to set them.

Event capture API