SDK Lifecycle
The states the SDK moves through, the calls that move it between them, and the mistakes that bite integrators.
Overview
The SDK is a singleton — importing it always gives you the same instance. There is nothing to construct, and you cannot run two of them on one page.
Its life is four scopes. The SDK session holds the other two: closing it closes everything still open inside. Page and panel sessions are siblings, not nested — swapping events closes and opens page sessions while a mounted panel carries on untouched.
| Scope | Bounded by | Notes |
|---|---|---|
| Configured | configure() | Site ID, platform, initial user settings. Lasts for the life of the page. |
| SDK session | userDidStartWatchingEvent() → userDidStopWatchingEvent() | Opens once, on the first start call. Everything below lives inside it. |
| Page session | one per loaded page config | Added and dropped as the loaded events change. |
| Panel session | renderPanel() → its cleanup function | Every mount and unmount of the panel UI. Many per SDK session, and independent of which page configs are loaded at the time. |
State machine
| State | Meaning |
|---|---|
| Idle | Module imported. Nothing configured. |
| Configured | Site ID and platform known. No session, no network yet. |
| Active | Page configs loaded, view models live, overlay mounted. |
| Panel mounted | Panel UI in the DOM, cleanup function in your hands. |
The self-transition on Active is the part integrators miss. Switching events is a repeat call to
userDidStartWatchingEvent(), which takes the refresh path — not stop-then-start.
userDidStopWatchingEvent() returns to Configured and unwinds every open scope innermost-first;
call it with a panel still mounted and it runs that panel's cleanup for you first.