Flush & Lifecycle

Batching behaviour

The SDK will not upload an event the moment you capture it. Instead:

1. Events are collected in memory.
2. After debounceMs (1500 ms by default) with no new event, the batch is sent.
3. If the upload fails, it is retried after retryDelayMs (10 000 ms by default).

For most applications that is what you want: a page that throws ten errors in a loop makes one request instead of ten.

Forcing a flush

An explicit flush sends every pending event immediately and resolves when the upload settles. It is worth calling in four places:

• Before navigating away. A redirect or a window.location assignment can tear the page down before the debounce window closes.
• After a critical error, when you are about to show an error page and would rather not rely on the user staying long enough for the timer to fire.
• Before logout, so the last events are attributed to the session that produced them.
• In tests, so an assertion runs after the request rather than racing it.

Browsers cut network requests short during beforeunload, so a flush there may not complete. Treat it as best-effort rather than a guarantee.

Lifecycle

Single-page applications. Initialize once at startup. Batching survives client-side route changes; there is nothing to re-arm per route.

Server-side rendering. The SDK is browser-only. In an SSR framework, initialization has to be guarded so it only runs where window exists — except in the framework packages, where setup is deliberately safe to run during SSR so that component-level helpers resolve on the server. The Svelte and Vue pages cover that difference for their frameworks.

Tuning

Lower debounceMs when you want events to land fast and can afford more requests; raise it on a high-traffic page where a single upload per burst matters more than latency. The retry delay should stay comfortably above your longest expected ingest hiccup, since a failed batch is re-queued rather than dropped.