SDK Overview

Userplane offers two integration paths depending on how much control you need. Most teams start with the embed script and add the npm SDK later if they need programmatic control.

Embed script (zero-code)

The embed script is a single <script> tag you add to your site. It handles everything automatically — loading the recorder, parsing recording links, and managing cross-tab state.

<script src="https://cdn.userplane.io/embed/script.js" data-workspace="ws_abc123" defer></script>

This is the recommended starting point. It works with any site and requires no build step. See Installation for setup instructions.

npm SDK (programmatic)

The @userplane/sdk package gives you a JavaScript API for full control over the recording lifecycle. Use it when you need to:

Trigger recordings from your UI — open the recorder from a button, menu, or support widget instead of relying on link clicks.
Attach metadata — send user IDs, account info, feature flags, or session context alongside recordings so your support team has full context.
Query recording state — check whether a recording is active, get the session ID, or read connection status to build custom UI.

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

// Initialize once on page load
initialize({ workspaceId: 'ws_abc123' });

// Attach context for support
setMetadata({
  userId: user.id,
  plan: user.plan,
  appVersion: __APP_VERSION__,
});

// Open the recorder from a support button
document.getElementById('help-btn').addEventListener('click', () => {
  open();
});

Choosing the right path

	Embed script	npm SDK
Setup	One `<script>` tag	`npm install @userplane/sdk`
Recording links	Work automatically	Work automatically
Programmatic open/close	No	Yes
Custom metadata	No	Yes
Recording state queries	No	Yes
Build step required	No	Yes

You can use both together. The embed script handles the baseline, and the SDK adds programmatic capabilities on top.

Framework guides

For framework-specific installation instructions, see the guide for your stack:

React

Next.js

Vue

Nuxt

Angular

SvelteKit

Astro

TanStack Start

Static HTML

Next steps

Web SDK Reference — full API for initialization, recorder control, and state inspection.
Metadata SDK Reference — attach custom key-value data to recordings.
Installation — set up the embed script.

Getting Started

AI Agents

SDK Reference

Framework Guides

Platform Guides

Privacy & Data

Embed script (zero-code)

npm SDK (programmatic)

Choosing the right path

Framework guides

React

Next.js

Vue

Nuxt

Angular

SvelteKit

Astro

TanStack Start

Static HTML

Next steps

​Embed script (zero-code)

​npm SDK (programmatic)

​Choosing the right path

​Framework guides

React

Next.js

Vue

Nuxt

Angular

SvelteKit

Astro

TanStack Start

Static HTML

​Next steps

Embed script (zero-code)

npm SDK (programmatic)

Choosing the right path

Framework guides

Next steps