Web SDK

The @userplane/sdk package provides a JavaScript API for integrating Userplane into your web application. Use it to initialize the SDK, programmatically trigger recording flows, query recording state, and attach custom metadata. For most setups, you only need the embed script (see Installation). The SDK package is for when you need programmatic control — for example, triggering a recording from a button in your app or attaching user-specific metadata.

Installation

npm install @userplane/sdk

yarn add @userplane/sdk

pnpm add @userplane/sdk

bun add @userplane/sdk

Initialization

`initialize(options?)`

Initializes the Userplane SDK. Call this once when your application loads. Subsequent calls are ignored.

import { initialize } from '@userplane/sdk';

initialize({
  workspaceId: 'ws_abc123',
});

Parameters

Parameter	Type	Default	Description
`options`	`InitializeOptions`	`{}`	Configuration options (optional)

`InitializeOptions`

Property	Type	Default	Description
`workspaceId`	`string \| string[]`	Read from `<meta name="userplane:workspace">`	Your workspace ID. Can be a single ID or an array for multi-workspace setups.
`openImmediately`	`boolean \| string`	`true`	Controls auto-open behavior. `true`: auto-open when recording URL params are detected. `false`: don’t auto-open. `string`: a recording token to open immediately.
`captureEnabled`	`boolean`	`true`	Whether to mount the background capture iframe for collecting console logs and network requests.
`parseUserplaneData`	`(href: string) => SerializableUserplaneData \| null`	Built-in parser	Custom function to parse `userplane-action` and `userplane-token` from the URL. Use this if your app uses non-standard URL routing.
`applyUserplaneData`	`(data: SerializableUserplaneData) => string`	Built-in handler	Custom function for applying Userplane data to the URL, used during cross-tab sync.
`excludeCaptureEndpoints`	`string[]`	`[]`	URLs to exclude from network log capture. Merged with Userplane’s internal endpoints. Useful for filtering out auth, payment, or analytics calls.

Examples

Basic initialization:

import { initialize } from '@userplane/sdk';

initialize({
  workspaceId: 'ws_abc123',
});

Disable auto-open (manual control):

initialize({
  workspaceId: 'ws_abc123',
  openImmediately: false,
});

// Later, open the recorder manually
document.getElementById('record-btn').addEventListener('click', () => {
  open();
});

Open with a specific recording token:

initialize({
  workspaceId: 'ws_abc123',
  openImmediately: 'rec_token_xyz',
});

Multiple workspaces:

initialize({
  workspaceId: ['ws_abc123', 'ws_def456'],
});

Recorder control

`open(token?)`

Opens the recording flow for the user. Returns true if the recorder was opened, false otherwise (e.g. if the SDK is not initialized or the recorder is already mounted).

Parameter	Type	Default	Description
`token`	`string`	From URL params	Recording token. If omitted, the SDK uses the token from the current URL query parameters.

Returns: boolean

import { open } from '@userplane/sdk';

// Open using token from URL params
open();

// Open with a specific token
open('rec_token_xyz');

`unmount()`

Closes and unmounts the recorder. If background capture is enabled, the capture iframe is re-mounted after the recorder is removed.

import { unmount } from '@userplane/sdk';

unmount();

`isInitialized()`

Returns true if the SDK has been initialized.

import { isInitialized } from '@userplane/sdk';

if (isInitialized()) {
  // SDK is ready
}

`isRecorderMounted()`

Returns true if the recorder is currently mounted and visible.

import { isRecorderMounted } from '@userplane/sdk';

if (isRecorderMounted()) {
  // Recorder is open
}

Recording state

`getRecordingState()`

Returns the current recording state. Returns: RecordingState — one of 'inactive', 'active', or 'retained'

State	Description
`inactive`	No recording is in progress
`active`	A recording is currently in progress
`retained`	A recording session exists but the recorder is not actively recording

import { getRecordingState } from '@userplane/sdk';

const state = getRecordingState();

if (state === 'active') {
  // Show a "recording in progress" indicator
}

`getRecordingContext()`

Returns the full recording context, or null if no context is available. Returns: RecordingContext | null

interface RecordingContext {
  state: RecordingState;
  sessionInfo: RecordingSessionInfo | null;
  tabUnloadEnabled: boolean;
}

interface RecordingSessionInfo {
  workspaceId: string;
  sessionId: string;
  linkId?: string;
}

import { getRecordingContext } from '@userplane/sdk';

const context = getRecordingContext();

if (context?.sessionInfo) {
  console.log('Session:', context.sessionInfo.sessionId);
  console.log('Link:', context.sessionInfo.linkId);
}

`getSessionId()`

Returns the current recording session ID, or null if no session is active. Returns: string | null

import { getSessionId } from '@userplane/sdk';

const sessionId = getSessionId();

`getLinkId()`

Returns the recording link ID for the current session, or null if no session is active. Returns: string | null

import { getLinkId } from '@userplane/sdk';

const linkId = getLinkId();

Tab management

`getTabRef()`

Returns the unique tab reference for this browser tab. This is persisted in sessionStorage for the lifetime of the tab and is used internally to manage cross-tab recording state. Returns: string | null

import { getTabRef } from '@userplane/sdk';

const tabRef = getTabRef();

`clearTabRef()`

Clears the tab reference from sessionStorage. A new reference is generated on the next initialization.

import { clearTabRef } from '@userplane/sdk';

clearTabRef();

Connection state

`isBridgeConnected()`

Returns true if the bridge connection between the SDK and the recorder iframe is established. Useful for debugging integration issues. Returns: boolean

import { isBridgeConnected } from '@userplane/sdk';

if (!isBridgeConnected()) {
  console.warn('Userplane bridge not connected');
}

HTML attributes and meta tags

The SDK recognizes HTML attributes and meta tags for configuring blur and workspace identity.

Blur attributes

Use data-userplane-blur to blur sensitive elements in recordings:

<div data-userplane-blur>
  <input type="text" placeholder="Credit card number" />
</div>

To exclude an element from blur:

<div data-userplane-blur="false">
  <p>This content will not be blurred.</p>
</div>

You can also use the .userplane-mask CSS class or <meta name="userplane:blur"> tags. See the Sensitive Data Redaction Developer Guide for the full list of blur methods and third-party compatibility.

Workspace meta tag

If you don’t pass workspaceId in initialize(), the SDK reads it from meta tags:

<meta name="userplane:workspace" content="ws_abc123" />

URL parameters

When a customer opens a recording link, Userplane appends these query parameters to the URL:

Parameter	Description
`userplane-token`	The recording session token
`userplane-action`	The action type (`recording`, `verify`, or `capture`)
`userplane-workspace`	The workspace ID

The SDK parses these automatically on initialization. If your app uses custom URL routing, you can provide a custom parser via the parseUserplaneData option.

Common patterns

Trigger recording from a support button

import { initialize, open, isRecorderMounted } from '@userplane/sdk';

initialize({
  workspaceId: 'ws_abc123',
  openImmediately: false,
});

document.getElementById('help-btn').addEventListener('click', () => {
  if (!isRecorderMounted()) {
    open();
  }
});

Show recording state in your UI

import { getRecordingState } from '@userplane/sdk';

function updateRecordingIndicator() {
  const state = getRecordingState();
  const indicator = document.getElementById('recording-indicator');

  if (state === 'active') {
    indicator.style.display = 'block';
  } else {
    indicator.style.display = 'none';
  }
}

Correlate recordings with your own analytics

import { getSessionId, getLinkId } from '@userplane/sdk';

// Send to your analytics tool
analytics.track('recording_started', {
  userplaneSessionId: getSessionId(),
  userplaneLinkId: getLinkId(),
});

Integration with recording links

The SDK works alongside recording links. When a customer opens a recording link on a page where the SDK is initialized, the SDK can provide additional context:

Custom metadata is attached to the recording.
Blur attributes are respected during capture.
Domain recording preferences are applied.

Metadata SDK — attach custom metadata to recordings.
Installation — install and configure the embed script.
Sensitive Data Redaction Developer Guide — configure blur to protect sensitive content.
Recording Data Reference — what data is captured.

Getting Started

AI Agents

SDK Reference

Framework Guides

Platform Guides

Privacy & Data

Installation

Initialization

`initialize(options?)`

Parameters

`InitializeOptions`

Examples

Recorder control

`open(token?)`

`unmount()`

`isInitialized()`

`isRecorderMounted()`

Recording state

`getRecordingState()`

`getRecordingContext()`

`getSessionId()`

`getLinkId()`

Tab management

`getTabRef()`

`clearTabRef()`

Connection state

`isBridgeConnected()`

HTML attributes and meta tags

Blur attributes

Workspace meta tag

URL parameters

Common patterns

Trigger recording from a support button

Show recording state in your UI

Correlate recordings with your own analytics

Integration with recording links

​Installation

​Initialization

​initialize(options?)

​Parameters

​InitializeOptions

​Examples

​Recorder control

​open(token?)

​unmount()

​isInitialized()

​isRecorderMounted()

​Recording state

​getRecordingState()

​getRecordingContext()

​getSessionId()

​getLinkId()

​Tab management

​getTabRef()

​clearTabRef()

​Connection state

​isBridgeConnected()

​HTML attributes and meta tags

​Blur attributes

​Workspace meta tag

​URL parameters

​Common patterns

​Trigger recording from a support button

​Show recording state in your UI

​Correlate recordings with your own analytics

​Integration with recording links

​Related articles

Installation

Initialization

`initialize(options?)`

Parameters

`InitializeOptions`

Examples

Recorder control

`open(token?)`

`unmount()`

`isInitialized()`

`isRecorderMounted()`

Recording state

`getRecordingState()`

`getRecordingContext()`

`getSessionId()`

`getLinkId()`

Tab management

`getTabRef()`

`clearTabRef()`

Connection state

`isBridgeConnected()`

HTML attributes and meta tags

Blur attributes

Workspace meta tag

URL parameters

Common patterns

Trigger recording from a support button

Show recording state in your UI

Correlate recordings with your own analytics

Integration with recording links

Related articles