Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userplane.io/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers how to install Userplane in a React application built with Vite.

​
Adding the script

The fastest way to add Userplane is the CDN embed. Add these two tags to the <head> of your index.html: 
<meta name="userplane:workspace" content="YOUR_WORKSPACE_ID" />
<script type="module" src="https://cdn.userplane.io/embed/script.js"></script>
You can copy the snippet with your workspace ID pre-filled from Workspace Settings > Domains in the Userplane dashboard.

​
npm SDK

Use the npm SDK when you need programmatic control — triggering recordings from a button, attaching user metadata, or reading recording state.

​
Installation

npm install @userplane/sdk

​
Initialization

Create a UserplaneProvider component and wrap your app with it in main.tsx. 
// src/providers/UserplaneProvider.tsx
import { useEffect } from 'react';
import { initialize } from '@userplane/sdk';

export function UserplaneProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    initialize({
      workspaceId: import.meta.env.VITE_USERPLANE_WORKSPACE_ID,
    });
  }, []);

  return <>{children}</>;
}

// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { UserplaneProvider } from './providers/UserplaneProvider';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <UserplaneProvider>
      <App />
    </UserplaneProvider>
  </StrictMode>
);
Because Vite React apps are pure client-side rendered, you can use a static import at the top of the file — no dynamic import() or SSR guards are needed. useEffect ensures initialize() runs once after mount.

​
URL parameters

When a customer opens a recording link, Userplane appends userplane-token and userplane-action to the URL. If your app uses a router that strips unknown search parameters (e.g. a protected route redirect), carry the userplane- prefixed params through: 
// Example: preserve params through a login redirect
const url = new URL(window.location.href);
const loginUrl = new URL('/login', window.location.origin);

for (const [key, value] of url.searchParams) {
  if (key.startsWith('userplane-')) {
    loginUrl.searchParams.set(key, value);
  }
}

window.location.href = loginUrl.toString();
See Installation for the full list of parameters.

​
Sensitive data

Add data-userplane-blur to any element you want blurred in recordings. See Sensitive Data Redaction for the full reference.

​
Metadata

Call set() after initialize() to attach user context to recordings: 
import { useEffect } from 'react';
import { initialize, set } from '@userplane/sdk';

export function UserplaneProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    initialize({ workspaceId: import.meta.env.VITE_USERPLANE_WORKSPACE_ID });
    set('environment', 'production');
  }, []);

  return <>{children}</>;
}
See Metadata SDK for the full API.

​
Example app

A complete React example is available at github.com/userplanehq/userplane-sdk-examples/tree/main/examples/react.
VariableDescription
VITE_USERPLANE_WORKSPACE_IDYour Userplane workspace ID
cd examples/react && npm install && npm run dev