Skip to main content
Userplane works without any code — but the SDK unlocks richer session data, custom metadata, and programmatic recording controls. This guide covers everything you need to integrate Userplane into your app.

​
What you’ll set up

  • Script or npm package installation
  • Domain verification (required for branded recording links)
  • Custom metadata to attach user/account context to recordings
  • Sensitive data redaction for compliance
  • Framework-specific configuration

​
Step 1: Install the SDK

You can load Userplane via CDN snippet or install it as an npm package.

​
Embed script (quickest)

Add this to the <head> of every page where you want recordings to work: 
<!-- Sets workspace ID for screen recording -->
<meta name="userplane:workspace" content="YOUR_WORKSPACE_ID" />

<!-- Loads Userplane screen recording script -->
<script type="module" src="https://cdn.userplane.io/embed/script.js"></script>

​
npm

npm install @userplane/sdk

import { initialize } from '@userplane/sdk';
initialize({ workspaceId: 'YOUR_WORKSPACE_ID' });
Your workspaceId is in Workspace Settings > General. See Web SDK Reference for the full API and Installation Guide for platform-specific notes.

​
Step 2: Verify your domain

Domain verification is required before your support team can create branded recording links on your domain. Userplane verifies ownership by checking that the embed script is present on your site.
1

Add your domain in the dashboard

Go to Workspace Settings > Domains and click Add Domain.
2

Deploy the script

The embed script from Step 1 is what Userplane checks for during verification. Make sure it is deployed to a publicly accessible page — verification will fail if the page is behind a login wall or not yet deployed.
3

Verify

Click Verify in the dashboard (or ask your workspace admin to do it). Verification runs immediately. The verification token expires after 5 minutes, so trigger it once the script is live.
See Domain Verification for full details and troubleshooting.

​
Step 3: Attach metadata to recordings

Metadata lets you attach user and account context to every recording so your support team sees who the customer is without having to ask. 
import { set } from '@userplane/sdk';

// Call after your user is authenticated
set('userId', user.id);
set('email', user.email);
set('name', user.name);
set('accountId', account.id);
set('plan', account.plan);
Metadata appears in the Info tab of every recording from that user. See Metadata SDK for the full reference.

​
Dynamic metadata

Use metadata() to capture values at recording submission time — useful for SPAs where context changes without a page reload: 
import { set, metadata } from '@userplane/sdk';

// Static values set once at login
set('userId', user.id);
set('email', user.email);

// Dynamic values captured fresh when the recording is submitted
metadata(() => ({
  accountId: getCurrentAccount().id,
  plan: getCurrentAccount().plan,
  page: window.location.pathname,
}));

​
Step 4: Configure sensitive data redaction

Prevent sensitive data from appearing in recordings before you go to production.

​
Blur DOM elements

Add data-userplane-blur to any element you want blurred in the recording: 
<input type="password" data-userplane-blur />
<div class="credit-card-number" data-userplane-blur>4242 4242 4242 4242</div>
See Sensitive Data Redaction for the full list of privacy controls — including CSS class and meta tag approaches, and third-party selector compatibility.

​
Exclude network requests

Prevent specific URLs from being captured in network logs by passing excludeCaptureEndpoints to initialize(): 
initialize({
  workspaceId: 'YOUR_WORKSPACE_ID',
  excludeCaptureEndpoints: ['/api/auth', '/api/payment', 'stripe.com'],
});
These are merged with Userplane’s internal excluded endpoints.

​
Step 5: Choose your framework

Userplane works with any JavaScript framework. Check the guide for yours:

React

Next.js

Vue

Nuxt

Angular

SvelteKit

Astro

TanStack Start

Static HTML

​
Programmatic recording controls

Once the SDK is installed, you can control recording sessions programmatically: 
import { open, unmount, getRecordingState } from '@userplane/sdk';

// Open the recording flow
open();

// Close the recorder
unmount();

// Check current state
const state = getRecordingState(); // 'inactive' | 'active' | 'retained'
See Recorder Control API for full details.

​
Checklist before going live

  • Embed script installed on every page (or initialize() called via the npm package)
  • workspaceId is set correctly (not hardcoded in the repo — use env vars)
  • Domain verified in the dashboard
  • set() called after user authentication to attach metadata
  • Sensitive fields marked with data-userplane-blur
  • excludeCaptureEndpoints set in initialize() to exclude auth/payment URLs from network logs
  • Tested a recording end-to-end in a staging environment

​
Next steps

Web SDK Reference

Full API reference for initialization, controls, and events

Metadata SDK

Attach user and account context to every recording

Sensitive Data Redaction

Full privacy controls — masking, exclusions, and redaction

Recording Data Reference

What data is collected and how it’s stored