UI Monitor Client API
The hosted capture script exposes a small command-queue API for controlling capture from your own code: litmus('function', { ...params }). It works even before the script has finished loading, since calls made against the initial stub are queued and replayed once the real script is ready. This is the same pattern tools like Segment or Intercom use for their own embeds.
<script>
litmus('init', { waitForStart: true })
// ... later, once you're ready ...
litmus('start')
</script>
Functions
| Function | Params | What it does |
|---|---|---|
init | { waitForStart, optOut } | Declares capture settings from code. waitForStart: true suppresses the default auto-start so you can call start() yourself later. optOut: true opts the current visitor out (persisted, see below). See "Guaranteeing init runs in time" below for how to place this call safely. |
set | { ...properties } | Attaches arbitrary key/value properties to the current session, sent along with every chunk. |
identify | { uid } | Marks the session with a stable visitor id, so sessions from the same person can be stitched together later. |
start | — | Starts (or resumes) recording. Idempotent, calling it while already recording does nothing. Does not change the session id. |
stop | — | Stops recording without ending the session. Calling start() again later takes a fresh checkpoint but keeps the same session id. Use this to pause through a sensitive step (entering a payment card, say) without splitting the session in two. |
clear | — | Ends the current session and starts a brand-new one with a fresh id. Use on logout, for instance, so the next session isn't attributed to the previous visitor. Does not change opt-out status; clearing session state on logout shouldn't silently opt someone back in or out. |
getSessionId | (callback) | Returns the current session id via callback (queued calls can't return synchronously). Useful for correlating a session with your own analytics or support tooling. |
Opt-out persists in localStorage, not per-session storage. A visitor's opt-out choice should survive closing the tab, unlike the session id itself, which is deliberately short-lived.
Guaranteeing init runs in time
waitForStart/optOut only do what you want if they're applied before capture would otherwise auto-start. By default, capture starts as soon as the page finishes parsing (the browser's DOMContentLoaded event), not when the script itself loads and not waiting on images or other subresources.
There are two ways to guarantee your init call lands in time, and they suit different situations.
Set window.litmusInit before the snippet. This is the recommended default. A plain object assignment has no timing dependency at all, since it only relies on normal document order, not any browser event:
<script>window.litmusInit = { waitForStart: true }</script>
<!-- the embed snippet can go anywhere after this — same page, head or body, doesn't matter -->
Call litmus('init', {...}) directly, when you already know the value at page-load time but the code that knows it isn't the snippet itself. This is safe anywhere in a normal, synchronously-parsed part of the page, but not safe from code that runs asynchronously relative to page load (inside a window.onload handler, a script loaded via async/defer, or code that runs after a JS framework hydrates) — that code could easily run after capture has already auto-started.
Neither option helps if the decision genuinely can't be known until well after the page has loaded (waiting on a cookie-consent banner's response, for instance, which might not resolve for seconds or longer). For that case, don't configure waitForStart/optOut on an already-injected snippet at all. Instead, don't inject the snippet (or set window.litmusInit, then inject the snippet right after) until the decision is actually made. An embed that's never added to the page can't start capturing, full stop, which is a stronger guarantee than trying to race a configuration call against auto-start.
Related
- Monitors — how UI Monitor capture and matching work overall
- UI Monitor Privacy — what's protected automatically, and how to add your own rules
- UI Monitor Script Caching — how long a change (including an
initcall baked into a page) takes to reach every visitor