Documentation

Get your first session recording in under two minutes.

npm install webrec-sdk

import { WebRec } from 'webrec-sdk';

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

// Optional: identify logged-in users
WebRec.identify(user.id, {
  name: user.name,
  email: user.email,
});

That’s it. Sessions will appear in your dashboard within seconds. Your API key is available in Project Settings → API Keys.

Pass configuration to WebRec.init(). Only apiKey is required.

WebRec.init({
  apiKey: '...',
  sampling: {
    mousemove: 50,    // Throttle mouse events to every 50ms (false to disable)
    scroll: 150,      // Throttle scroll events to every 150ms
    input: 'last',    // 'last' = only final value, 'all' = every keystroke
  },
});

WebRec.init({
  apiKey: '...',
  privacy: {
    maskInputs: true,        // Mask email/tel inputs
    maskTextContent: false,  // Replace ALL text with asterisks
    blockSelectors: [],      // CSS selectors to block entirely
    ignoreSelectors: [],     // CSS selectors to ignore changes on
  },
});

Call identify() after your user logs in to link sessions to real users. Traits persist across page loads via localStorage.

WebRec.identify('user-123', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  plan: 'pro',              // custom property
  company: 'Acme Corp',    // custom property
});

When you identify a user, Webrec automatically back-fills all previous anonymous sessions from that browser, so you get a complete history.

Associate users with their company or team using group(). This enables organization-level analytics, filtering sessions by company, and tracking properties like plan or MRR.

WebRec.group('org-456', {
  name: 'Acme Corp',
  domain: 'acme.com',
  plan: 'enterprise',
  mrr: 15000,
  industry: 'SaaS',
  employeeCount: 250,
});

Call group() after identify() — typically on login or when the user’s organization context is known. The group association persists across page loads via localStorage.

WebRec.identify('user-123', {
  name: 'Jane Smith',
  email: 'jane@acme.com',
  plan: 'pro',           // custom property
  role: 'admin',         // custom property
  signupDate: '2025-01-15',  // custom property
});

Track business events like purchases, sign-ups, or feature usage:

WebRec.track('checkout_completed', {
  value: 99.00,
  currency: 'USD',
  item_count: 3,
});

WebRec.track('feature_used', {
  feature: 'dark_mode',
  source: 'settings',
});

Custom events appear in the session timeline, can be used as funnel steps, and are available in trend breakdowns.

Every session is recorded as a pixel-perfect DOM replay using rrweb. The replay player includes:

• Playback controls — play, pause, skip inactive, speed (1x–16x), fullscreen
• Timeline scrubber — with markers for errors (red), rage clicks (orange), and custom events (blue)
• Inspect mode — click any element during playback to see its selector, classes, attributes, and size
• DevTools panel — Console, Network, Events, Errors, and Custom Events tabs
• Right sidebar — session overview, device info, user profile, web vitals, AI summary
• AI summaries — one-click GPT-powered analysis of what happened in the session
• Sharing — generate a shareable link with optional password and expiration
• Comments — add timestamped comments for your team

Webrec automatically detects three types of user frustration:

Select pages from the page picker dropdown and switch between exact URL matching or base URL grouping to aggregate variants.

Deploy surveys directly in your app. Create them in the dashboard and they’re automatically shown to matching users via the SDK.

Webrec captures uncaught JavaScript errors and unhandled promise rejections automatically (when captureErrors: true).

• Errors are grouped by type + stack trace fingerprint
• Each group shows first/last occurrence, total count, and affected sessions
• Click any error to jump to the session replay at the exact moment
• Stack traces are displayed with source file, line, and column
• Filter by error type, message, URL, date range, and occurrence count

Webrec collects Core Web Vitals automatically:

View P75 values, rating distribution (good / needs improvement / poor), and daily trends in the Vitals page. Click any metric to see sessions filtered by performance rating.

Build conversion funnels to see where users drop off. Each step can be a page URL or a custom action/event.

• Add up to N steps with the page picker (auto-suggests your most visited pages)
• See conversion rate, drop-off count, and median time between each step
• Click any step to view the sessions that reached (or dropped off at) that point
• AI-powered conversion driver analysis shows which actions correlate with completion

Cohort retention analysis shows how many users return over time. Requires identified users (call WebRec.identify()).

Choose between daily, weekly, or monthly cohorts. The heatmap visualization colour-codes each cell by retention percentage — dark green means high retention.

Sankey flow diagrams visualise the most common paths users take through your site. See which pages users visit before and after any given page, with edge thickness proportional to traffic volume.

Filter by time period and start/end page. A “Top Paths” table below the diagram lists the most frequent multi-step paths with session counts.

Time-series analysis of key metrics with dimensional breakdowns. Choose a metric (sessions, users, errors, rage clicks, duration, page views), then break down by browser, OS, device, country, or page.

Line charts and stacked area charts with daily, weekly, or monthly granularity. Hover for detailed tooltips. Export data as CSV.

Build your own dashboards with drag-and-drop widgets. Available widget types:

• Metric — single number with trend indicator
• Time series — line/bar chart over time
• Funnel — embedded funnel visualization
• Table — tabular data with sorting
• Retention — cohort retention heatmap
• Journey — Sankey flow diagram

Start with a template or build from scratch. Each dashboard can be shared with your team.

Webrec supports consent-based recording out of the box. Three approaches:

WebRec.init({ apiKey: '...' });
WebRec.stop(); // No recording until consent

onUserConsent(() => {
  WebRec.start(); // Begin recording
});

// Only init after consent
onUserConsent(() => {
  WebRec.init({ apiKey: '...' });
});

• Legal basis: Legitimate interest (with proper disclosure) or explicit consent
• Data hosting: GCP europe-west2 (London). Session data stays in the EU
• Data retention: Configurable per plan (7, 90, or 365 days). Data is automatically purged after expiry
• Data subject rights: Access, erasure, and portability requests are supported. Contact support@webrec.app
• Data Processing Agreement: Available on request for enterprise plans
• Sub-processors: GCP (infrastructure), Stripe (billing only)
• No third-party cookies: Webrec uses zero third-party cookies. Session IDs are stored in sessionStorage; anonymous IDs in localStorage

Route SDK traffic through your own domain to avoid ad blockers and keep all requests first-party. This is the recommended production setup.

location /wr/ {
    proxy_pass https://api.webrec.app/v1/;
    proxy_set_header Host api.webrec.app;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

module.exports = {
  async rewrites() {
    return [
      {
        source: '/wr/:path*',
        destination: 'https://api.webrec.app/v1/:path*',
      },
    ];
  },
};

export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = 'api.webrec.app';
    url.pathname = url.pathname.replace('/wr/', '/v1/');
    return fetch(url, request);
  },
};

Then point the SDK at your proxy:

WebRec.init({
  apiKey: 'wr_your_project_key',
  endpoint: 'https://yourdomain.com/wr',
});

If your site uses a strict CSP, add these directives:

script-src 'self' https://api.webrec.app;
connect-src 'self' https://api.webrec.app;

If using a reverse proxy, replace https://api.webrec.app with your proxy domain. If using the CDN script tag, also add the CDN domain (https://unpkg.com or https://cdn.jsdelivr.net).

Webrec automatically detects SPA route changes by intercepting:

• history.pushState() and history.replaceState()
• popstate events (back/forward navigation)
• hashchange events

Each navigation is recorded as a page view event with from_url and to_url. No additional configuration needed — it works with React Router, Vue Router, Next.js, and any other client-side routing library.

Webrec can be fully self-hosted (open-source licence). The stack consists of three services:

• Web — Next.js dashboard (port 3000)
• API — Express.js ingest + REST API (port 8080)
• Jobs — Scheduled tasks (session close, AI summaries, retention cleanup)

Requirements: MySQL 8.0, GCS/S3-compatible object storage, Node.js 18+. Set SELF_HOSTED=true to disable billing and usage limits.

The sessions page shows all recorded sessions with powerful filtering:

Click any session to open the replay in a slide-over panel. The player includes:

• Timeline: scrub through the session with visual markers for errors, rage clicks, and events
• DevTools: Console (with level filtering), Network (with status/method/URL filtering), Events, Errors, and Custom Events tabs
• Sidebar: session overview, user info, device details, web vitals, AI summary, comments
• Navigation: previous/next session buttons to quickly scan through your session list
• Actions: favourite, share, open in full-page mode, delete

Export data as CSV from the sessions list, errors page, users page, and analytics views. Use the download icon in the toolbar.

REST API endpoints for programmatic access:

GET /api/projects/:projectId/sessions?format=csv
GET /api/projects/:projectId/errors?format=csv
GET /api/projects/:projectId/users?format=csv

All API requests require a valid session token (same auth used by the dashboard).

Organizations are the top-level container for projects, members, and billing. Create one during onboarding, or add more from the org switcher in the header.

Each organization has its own member list, billing plan, API keys, and SSO configuration.

Invite team members by email from Settings → Members. All plans include unlimited seats — no per-seat pricing.

Enterprise SSO via SAML 2.0 or OIDC. Configure in Settings → SSO:

1. Copy the Entity ID and ACS URL from the Service Provider Metadata section
2. Add these to your Identity Provider (Okta, Azure AD, Google Workspace, etc.)
3. Paste the IdP Entity ID, IdP SSO URL, and Certificate into Webrec
4. Enable SSO. Optionally enforce SSO to require all members to authenticate via your IdP

Webrec offers a free tier (100 sessions/month) and paid plans that scale with usage. All plans include unlimited team members. View your current usage and manage your subscription in Settings → Billing.

Overage is billed at the per-session rate for your plan. Set spend limits to cap costs. See the pricing page for full details.

Create issues directly from a session replay with one click. The issue automatically includes:

• Session replay link
• Error details and stack trace (if applicable)
• Device, browser, and OS info
• Steps to reproduce (from the session timeline)

Send alert notifications to a Slack channel. Configure in Project Settings → Integrations. Messages include formatted error details, session links, and quick-action buttons.

• Use a reverse proxy — eliminates CORS preflight overhead and avoids ad blockers
• Set sampleRate — if you have high traffic, recording 20–50% of sessions still gives statistically meaningful data
• Increase sampling.mousemove — throttling from 50ms to 100–200ms significantly reduces event volume with negligible replay quality loss
• Disable recordCanvas — canvas recording is CPU-intensive. Only enable if you need to replay canvas-based content
• Set minSessionDuration — discarding sessions under 2–3 seconds filters out bots and accidental visits
• Use ignoreUrls — skip recording on admin pages, internal tools, or healthcheck routes

• Keep maskAllInputs: true (default) — you rarely need actual form values for debugging
• Block sensitive sections — add wr-block to payment forms, personal data views, and admin panels
• Use consent-based recording — if required by your privacy policy, use the stop/start pattern
• Configure network exclusions — exclude domains that return sensitive data in responses
• Set appropriate retention — shorter retention windows reduce compliance scope
• Document your legal basis — include session recording in your privacy policy with clear disclosure

• Start with frustrated sessions — sort by frustration score to find the most problematic sessions first
• Use error click correlation — the Error Clicks page shows exactly which user actions trigger bugs
• Filter by error group — from the Errors page, click into a group to see all affected sessions
• Use the DevTools timeline — red markers on the timeline scrubber show exactly when errors occurred
• Create collections for investigations — group related sessions into a collection to share with your team
• Link to Jira/Linear — create issues directly from the replay with all context included automatically
• Use WebRec.getSessionUrl() — log it to your error reporting tool (Sentry, Bugsnag) to link errors to replays

import * as Sentry from '@sentry/browser';
import { WebRec } from 'webrec-sdk';

Sentry.init({ dsn: '...' });

// After WebRec init:
const sessionUrl = WebRec.getSessionUrl();
if (sessionUrl) {
  Sentry.setTag('webrec_session', sessionUrl);
}