Control lifecycle and runtime APIs

This page is the operational API guide for @oxvo/browser.

Runtime lifecycle

Method	What it does	Notes
start(startOptions?)	Starts capture and returns { success, ... }	Check result.success before assuming capture is active
stop()	Stops capture and returns sessionHash if available	Use returned hash to continue session context later
isActive()	Returns current browser activity state	Useful for guards in SPA route transitions
forceFlushBatch()	Immediately flushes buffered events	Helpful before controlled teardown flows
getSessionMeta()	Returns runtime session metadata	Includes session ID, user ID, metadata, browser info
getSessionLink({ withCurrentTime? })	Returns replay URL	withCurrentTime appends playback jump offset

Start options you will use most

const result = await browser.start({
  userID: 'user_42',
  metadata: {
    plan: 'pro',
    environment: 'production',
  },
  startNewSession: false,
  sessionHash: undefined,
});

• userID: sets the authenticated user for the session.
• metadata: key/value strings attached to the session.
• startNewSession: forces token reset and starts a new session identity.
• sessionHash: restores a previous session context created by stop().

Add identity and metadata during runtime

browser.identify('user_42', {
  email: 'jane.doe@example.com',
  name: 'Jane Doe',
});

browser.setVisitorID('anonymous_visitor_id');
browser.setMetadata('environment', 'production');

Send custom events and issues

browser.track('checkout_started', { step: 'shipping' });
browser.report('payment_error', { code: 'card_declined' });

window.addEventListener('error', event => {
  browser.handleError(event, { area: 'checkout' });
});

• Use track() for product behavior and feature milestones.
• Use report() for issue-like signals that should be easy to filter.
• Use handleError() to normalize browser error payloads.

Continue across page transitions with sessionHash

const sessionHash = browser.stop();

if (sessionHash) {
  await browser.start({ sessionHash });
}

Track websocket payloads explicitly

const wsEvents = browser.trackWs('chat-stream');

socket.addEventListener('message', event => {
  wsEvents?.('message', String(event.data), 'down');
});

trackWs() ignores payloads larger than 5 MB and event names longer than 255 chars.

Cold start and offline recording flows

Cold start buffer (capture before explicit start trigger)

await browser.coldStart({ userID: 'user_42' });

// later, after your own business condition:
await browser.start();

Offline recording and upload

const offline = browser.startOfflineRecording({ userID: 'user_42' }, () => {
  console.log('Offline session finished uploading');
});

offline?.saveBuffer();

// when network access is restored:
await browser.uploadOfflineRecording();

Analytics namespace

Enable analytics in constructor/configuration:

browser.configure({
  workspaceId: 'YOUR_WORKSPACE_ID',
  analytics: { active: true },
});

Then use the analytics API:

browser.analytics?.identify('user_42', {
  email: 'jane.doe@example.com',
  first_name: 'Jane',
});

browser.analytics?.track('checkout_completed', { value: 129 });
browser.analytics?.events.setProperty('plan', 'pro');
browser.analytics?.people.increment('support_tickets', 1);

Note: incident() and setAnalyticsToken() are available on class instances. If you use the singleton, call them through browser.getInstance().

📷 Image (optional): Browser SDK lifecycle and event flow
Why: Clarifies how start/stop, event emission, and replay link generation fit into one runtime lifecycle.
File: docs/images/sdk-browser-lifecycle-and-api-flow.png
AI prompt: "Clean product documentation flowchart for OXVO browser SDK lifecycle showing configure, start, identify, track/report, stop, sessionHash resume, and getSessionLink steps, plus analytics branch, modern SaaS style with neutral background and high-contrast typography, no third-party logos, synthetic labels only, 1600x1000."