Documentation

npm install @webrec/sdk

# or with yarn
yarn add @webrec/sdk

# or with pnpm
pnpm add @webrec/sdk

import { WebRec } from '@webrec/sdk';

WebRec.init({
  apiKey: 'your-project-api-key',
});

<script src="https://api.webrec.app/v1/webrec.min.js"></script>

<script>
  WebRec.init({
    apiKey: 'your-project-api-key',
  });
</script>

<!-- Via unpkg -->
<script src="https://unpkg.com/@webrec/sdk@latest/dist/webrec.umd.js"></script>

<!-- Or via jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@webrec/sdk/dist/webrec.umd.js"></script>

WebRec.init({
  apiKey: 'wr_proj_abc123',
  privacy: {
    maskInputs: true,          // Mask form input values (default true)
    maskTextContent: false,    // Mask all text content (default false)
    blockSelectors: ['.secret-panel'],
    ignoreSelectors: ['.analytics-only'],
  },
});

WebRec.init({
  apiKey: 'wr_proj_abc123',
  sampling: {
    mousemove: 50,     // Sample mousemove every 50ms (or true/false)
    scroll: 150,       // Sample scroll every 150ms
    input: 'last',     // Capture 'last' input value or 'all' keystrokes
  },
});

WebRec.init({
  apiKey: 'wr_proj_abc123',
  ignoreUrls: ['/admin.*', '/internal.*'],  // Skip these URLs
  allowUrls: ['/app.*', '/checkout.*'],     // Only record these URLs
});

WebRec.init({
  apiKey: 'wr_proj_abc123',
});

WebRec.identify('user_42', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  plan: 'pro',
});

WebRec.track('purchase_completed', {
  orderId: 'ORD-1234',
  total: 59.99,
  currency: 'USD',
});

// Start recording after consent
document.getElementById('consent-btn')
  .addEventListener('click', () => {
    WebRec.start();
  });

// Stop recording when user navigates to sensitive page
WebRec.stop();

// Cleanup on app unmount
WebRec.destroy();

const sessionId = WebRec.getSessionId();
console.log('Webrec session:', sessionId);

// Attach to support tickets, bug reports, etc.
fetch('/api/support', {
  method: 'POST',
  body: JSON.stringify({
    message: 'Help!',
    webrecSession: sessionId,
  }),
});

const url = WebRec.getSessionUrl();
// e.g. "https://app.webrec.app/projects/xxx/sessions/yyy"

if (WebRec.isRecording()) {
  console.log('Recording is active');
}

WebRec.init({
  apiKey: 'wr_proj_abc123',
  surveys: false,  // Disable the survey widget
});

WebRec.on('survey:shown', (survey) => {
  console.log('Survey shown:', survey.id);
});

WebRec.on('survey:completed', (survey, response) => {
  console.log('Survey completed:', survey.id, response);
});

WebRec.on('survey:dismissed', (survey) => {
  console.log('Survey dismissed:', survey.id);
});

WebRec.init({
  apiKey: 'wr_proj_abc123',
  frustration: {
    deadClickTimeout: 1000,    // ms to wait for response (default 1000)
    rageClickThreshold: 3,     // clicks in rapid succession (default 3)
    rageClickWindow: 800,      // ms window for rage clicks (default 800)
  },
});

// Default behavior: all inputs masked
WebRec.init({ apiKey: '...', maskAllInputs: true });

// To unmask specific inputs, add the wr-unmask class:
// <input class="wr-unmask" type="text" placeholder="Search..." />

<!-- Using CSS class -->
<div class="wr-block">
  This content will not appear in recordings.
</div>

<!-- Using data attribute -->
<div data-wr-block>
  <p>Sensitive information here</p>
</div>

<!-- Block specific sections -->
<section class="wr-block" id="payment-form">
  <input type="text" name="card-number" />
  <input type="text" name="cvv" />
</section>

WebRec.init({
  apiKey: '...',
  privacy: {
    maskTextContent: true,
    // You can still see page structure and user behavior,
    // but all text content is masked.
  },
});

WebRec.init({
  apiKey: '...',
  captureNetwork: true,
  ignoreUrls: [
    '/api/auth.*',        // Exclude auth endpoints
    'stripe\.com',       // Exclude payment URLs
  ],
});

// Initialize but don't record yet
WebRec.init({
  apiKey: '...',
});

// The SDK does not set cookies by default.
// It uses sessionStorage for the session ID.

// Call stop() immediately if you want to wait for consent:
WebRec.stop();

// Later, after user consents:
function onConsentGranted() {
  WebRec.start();
}

WebRec.init({
  apiKey: '...',
  respectDoNotTrack: false,  // Record even if DNT is enabled
});

// Initialize the SDK but stop recording immediately
WebRec.init({ apiKey: 'wr_proj_abc123' });
WebRec.stop();

// Integrate with your CMP (e.g., OneTrust, Cookiebot, etc.)
window.addEventListener('CookieConsentGiven', (e) => {
  if (e.detail.analytics === true) {
    WebRec.start();
  }
});

// Or with a simple cookie banner
document.getElementById('accept-cookies')
  .addEventListener('click', () => {
    WebRec.start();
  });

document.getElementById('reject-cookies')
  .addEventListener('click', () => {
    // Recording was already stopped, nothing to do
  });

WebRec.init({
  apiKey: 'wr_proj_abc123',
  maskAllInputs: true,            // Mask all form inputs
  respectDoNotTrack: true,         // Respect browser DNT
  captureNetwork: true,
  ignoreUrls: ['/api/auth.*'],     // Don't capture auth requests
  privacy: {
    maskInputs: true,
    maskTextContent: false,
    blockSelectors: [
      '.personal-data',           // Block PII sections
      '#payment-form',            // Block payment forms
      '[data-gdpr-sensitive]',    // Block custom-marked elements
    ],
  },
});

'use client';

import { useEffect } from 'react';
import { WebRec } from '@webrec/sdk';

export default function RootLayout({ children }) {
  useEffect(() => {
    WebRec.init({
      apiKey: process.env.NEXT_PUBLIC_WEBREC_KEY,
    });

    return () => {
      WebRec.destroy();
    };
  }, []);

  return <html><body>{children}</body></html>;
}

import { WebRec } from '@webrec/sdk';

export default defineNuxtPlugin(() => {
  WebRec.init({
    apiKey: useRuntimeConfig().public.webrecKey,
  });
});

import { WebRec } from '@webrec/sdk';

document.addEventListener('DOMContentLoaded', () => {
  WebRec.init({
    apiKey: 'wr_proj_abc123',
  });
});

// Export sessions as CSV
GET /v1/projects/:projectId/export/sessions?format=csv
  &from=2026-01-01&to=2026-03-01

// Export errors as CSV
GET /v1/projects/:projectId/export/errors?format=csv
  &from=2026-01-01&to=2026-03-01

// Export analytics data as CSV
GET /v1/projects/:projectId/export/analytics?format=csv
  &metric=pageviews&from=2026-01-01&to=2026-03-01

// Headers
Authorization: Bearer <your-api-key>

// List surveys
GET /v1/projects/:projectId/surveys

// Create a survey
POST /v1/projects/:projectId/surveys
{
  "name": "Feature satisfaction",
  "type": "rating",
  "question": "How satisfied are you with this feature?",
  "targeting": {
    "url_contains": "/dashboard"
  }
}

// Get survey responses
GET /v1/projects/:projectId/surveys/:surveyId/responses

// Headers
Authorization: Bearer <your-api-key>

// Add tags to a session
POST /v1/projects/:projectId/sessions/:sessionId/tags
{
  "tags": ["bug", "checkout-flow"]
}

// Create a collection
POST /v1/projects/:projectId/collections
{
  "name": "Sprint 42 Review",
  "session_ids": ["sess_abc", "sess_def", "sess_ghi"]
}

// List saved search views
GET /v1/projects/:projectId/views

// Headers
Authorization: Bearer <your-api-key>

// After successful authentication
async function onLogin(user) {
  WebRec.identify(user.id, {
    name: user.name,
    email: user.email,
    plan: user.subscription.plan,
    company: user.company?.name,
  });
}

// Track each step of a checkout funnel
WebRec.track('checkout_started');

// ... user fills in shipping
WebRec.track('shipping_completed', { method: 'express' });

// ... user enters payment
WebRec.track('payment_entered');

// ... order confirmed
WebRec.track('order_completed', {
  orderId: order.id,
  total: order.total,
  items: order.items.length,
});

// Errors are captured automatically, but you can
// attach the session ID to your own error reports:
window.addEventListener('error', (event) => {
  myErrorTracker.report({
    message: event.message,
    stack: event.error?.stack,
    webrecSessionId: WebRec.getSessionId(),
    webrecSessionUrl: WebRec.getSessionUrl(),
  });
});

// React example with cleanup
import { useEffect } from 'react';
import { WebRec } from '@webrec/sdk';

function App() {
  useEffect(() => {
    WebRec.init({ apiKey: 'wr_proj_abc123' });
    return () => WebRec.destroy();
  }, []);

  return <div>...</div>;
}