Documentation

npm install webrec-sdk

# or with yarn
yarn add webrec-sdk

# or with pnpm
pnpm add webrec-sdk

Then import and initialise in your application entry point:

import { WebRec } from 'webrec-sdk';

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

For sites without a bundler, load the SDK directly:

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({ apiKey: 'wr_your_project_key' });
</script>

If the site is deployed on Vercel, the Webrec integration connects a Vercel project to a Webrec project and writes the API key into it as NEXT_PUBLIC_WEBREC_API_KEY, on Production, Preview and Development. You still install the SDK, but there is no key to copy across by hand and no key sitting in your repository.

import { WebRec } from 'webrec-sdk';

WebRec.init({ apiKey: process.env.NEXT_PUBLIC_WEBREC_API_KEY });

Redeploy for the variable to take effect. Disconnecting the project removes the variable the integration created, and nothing else.

You can also load from a public CDN:

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

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

Initialise once in a top-level component or layout. Use useEffect to ensure it only runs client-side.

'use client';
import { useEffect } from 'react';
import { WebRec } from 'webrec-sdk';

export function WebrecProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    WebRec.init({ apiKey: 'wr_your_project_key' });
    return () => WebRec.destroy();
  }, []);

  return <>{children}</>;
}

import { WebRec } from 'webrec-sdk';

export default defineNuxtPlugin(() => {
  WebRec.init({ apiKey: 'wr_your_project_key' });
});

For Vue 3 without Nuxt, call WebRec.init() in your main.ts after createApp().

Download the pre-configured plugin from your Project Settings → Installation → WordPress tab. It comes with your API key baked in. Just upload and activate.

Or add this to your theme’s functions.php:

function webrec_tracking_script() {
  echo '<script src="https://api.webrec.app/v1/webrec.min.js"></script>';
  echo '<script>WebRec.init({ apiKey: "wr_your_project_key" });</script>';
}
add_action('wp_head', 'webrec_tracking_script');

The WordPress plugin includes additional features:

• Automatic user identification: logged-in WordPress users are identified with their name, email, and role
• Admin exclusion: skip recording for admin users (enabled by default)
• Settings page: configure privacy options under Settings → Webrec
• Caching compatible: works with WP Super Cache, W3 Total Cache, and other caching plugins

Add Webrec via Google Tag Manager in 4 steps:

1. In GTM, go to Tags → New
2. Choose Custom HTML as the tag type
3. Paste the code below
4. Set the trigger to All Pages, save, and publish

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
    respectDoNotTrack: true,
  });
</script>

<script>
  // Read user data from GTM data layer
  var userId = {{DL - User ID}};
  var userName = {{DL - User Name}};
  var userEmail = {{DL - User Email}};

  if (userId && window.WebRec) {
    WebRec.identify(userId, {
      name: userName,
      email: userEmail,
    });
  }
</script>

Add Webrec to your Shopify store by editing your theme code:

1. In Shopify admin, go to Online Store → Themes
2. Click … → Edit code on your active theme
3. Open layout/theme.liquid
4. Paste this just before the closing </head> tag

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
  });

  {% if customer %}
    WebRec.identify('{{ customer.id }}', {
      name: '{{ customer.name }}',
      email: '{{ customer.email }}',
    });
  {% endif %}
</script>

This works with all Shopify themes including Dawn, and is compatible with Shopify’s Online Store 2.0.

Add Webrec to your Webflow site in two steps:

1. Go to Project Settings → Custom Code
2. Paste this in the Head Code section

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
    respectDoNotTrack: true,
  });
</script>

Click Save, then Publish your site. Recording starts on all pages automatically.

Add Webrec to your Squarespace site:

1. Go to Settings → Advanced → Code Injection
2. Paste this in the Header section
3. Click Save

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
    respectDoNotTrack: true,
  });
</script>

Works on all pages automatically. Compatible with all Squarespace templates (7.0 and 7.1).

Add Webrec to your Wix site:

1. Go to Settings → Custom Code (or Tracking & Analytics)
2. Click + Add Custom Code
3. Paste the code below
4. Set placement to Head and apply to All pages
5. Click Apply

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
    respectDoNotTrack: true,
  });
</script>

Works on all pages automatically. If you use Wix Members, you can identify users with a Velo code snippet.

Add Webrec to your Framer site:

1. Go to Site Settings → General → Custom Code
2. Paste this in the Head section
3. Publish your site

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
  });
</script>

Add Webrec to your Ghost blog:

1. Go to Settings → Code Injection
2. Paste this in the Site Header section
3. Click Save

<script src="https://api.webrec.app/v1/webrec.min.js"></script>
<script>
  WebRec.init({
    apiKey: 'wr_your_project_key',
    maskAllInputs: true,
  });
</script>

Any key-value pairs passed to group() (beyond name and domain) are stored as custom properties. These are fully searchable and filterable:

• String properties: plan, industry, tier
• Numeric properties: mrr, employeeCount, seats (supports range queries like > 10000)
• Boolean properties: isEnterprise, hasSso

Similarly, any traits passed to identify() beyond name and email are stored as searchable user properties:

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

These appear on the user detail page and can be used in filters and segments.

To wait for user consent before recording, call stop() immediately after init(), then start() when consent is granted:

WebRec.init({ apiKey: '...' });
WebRec.stop(); // Paused, no data captured

// When user grants consent:
WebRec.start(); // Recording begins

Call destroy() for full cleanup (removes all event listeners, interceptors, and internal state). You can call init() again afterwards.

// In React useEffect cleanup:
return () => WebRec.destroy();

Sessions automatically rotate after 30 minutes of inactivity (configurable via sessionTimeout). A new session ID is generated and the old session is finalised.

3 or more clicks within 30px of each other in under 800ms. These indicate an element that isn’t responding as expected.

Clicks on interactive elements (buttons, links, inputs) that produce no DOM change, navigation, or network request within 2 seconds.

Clicks that are followed by a JavaScript error within 1 second. These help you find which user actions trigger bugs.

Every session gets a composite frustration score (0–100) based on rage clicks, dead clicks, error clicks, and error count. Use this to prioritise which sessions to review.

Aggregated click density maps overlaid on your pages. Filter by device type (desktop, tablet, mobile), URL, and time period. Click data is bucketed into a 5px grid for smooth visualisation.

See how far users scroll on each page. Scroll depth is tracked as a percentage (0–100%) and reported per session when the user navigates away or the tab becomes hidden.

• NPS: Net Promoter Score (0–10 scale)
• Rating: 1–5 star rating
• Single Choice: radio button selection
• Multiple Choice: checkbox selection
• Open Text: free-form text response

Control who sees the survey and when:

• URL match: show on specific pages (supports regex)
• Show after: delay N seconds before displaying
• Show to %: only show to a percentage of visitors
• Once per session: prevent re-showing in the same session

Customise position (bottom-right, bottom-left, bottom-center), theme (light/dark), and primary colour. Surveys render in a Shadow DOM so your site’s CSS won’t interfere.

All form inputs are masked by default (maskAllInputs: true). Password fields are always masked regardless of configuration. Users see *** in the replay instead of actual values.

Completely exclude elements from recordings:

<!-- Block by class -->
<div class="wr-block">This entire element is excluded</div>

<!-- Block by data attribute -->
<div data-wr-block>Also excluded</div>

<!-- Block by CSS selector (in config) -->
WebRec.init({
  apiKey: '...',
  blockSelector: '.sensitive-data, #credit-card-form',
});

Blocked elements are replaced with a placeholder in the replay. Ignored elements (wr-ignore) are visible but changes within them are not recorded.

For maximum privacy, enable privacy.maskTextContent: true to replace ALL visible text with asterisks. Useful for industries handling highly sensitive data.

Sensitive query parameters are automatically stripped from captured URLs: token, key, password, secret, auth, access_token, api_key, jwt, session_token.

Request and response bodies are only captured for payloads under 16 KB. Configure excluded domains and patterns in Project Settings.

Set respectDoNotTrack: true (default) to automatically skip recording for users who have enabled DNT in their browser.

Reduce data volume by only recording a percentage of sessions:

WebRec.init({
  apiKey: '...',
  sampleRate: 50, // Record 50% of sessions
});

Reduce CPU and network overhead by throttling high-frequency events:

WebRec.init({
  apiKey: '...',
  sampling: {
    mousemove: 100,    // Throttle to every 100ms (default: 50)
    scroll: 250,       // Throttle to every 250ms (default: 150)
    input: 'last',     // Only capture final input value
  },
});

The Webrec SDK is designed for minimal impact:

• Bundle size: 50 KB gzipped (170 KB raw)
• CPU overhead: < 1% on modern devices
• Network: batched + gzipped, typically 5–20 KB per flush
• Memory: events are evicted when queue exceeds maxQueueSize

When captureNetwork: true, all fetch() and XMLHttpRequest calls are recorded with method, URL, status, duration, and body (text/JSON under 16 KB). Sensitive query parameters are automatically redacted.

Configure in Project Settings:

• Body capture mode: all / errors only / none
• Excluded domains: skip recording for specific third-party APIs
• Excluded patterns: regex patterns to skip
• Allowed methods: only capture specific HTTP methods

When captureConsole: true, all console.log, console.warn, console.error, console.debug, and console.info calls are captured (messages truncated to 5,000 characters). Visible in the session DevTools panel.

• User: name, email, user ID, identified/anonymous
• Session: URL, duration, error count, click count, active status
• Device: browser, OS, device type, screen dimensions
• Location: country, city
• Behaviour: has rage clicks, has dead clicks, frustration score, has errors
• Time: session start date, time of day

Save any filter combination as a named view. Views can be shared with your team or kept private. Switch between views instantly from the dropdown.

Sort by most recent or most frustrated (highest frustration score first). Use the settings cog to hide short sessions (< 1 second).

The Users page lists all identified users with session count, last seen date, and average session duration. Full-text search across name, email, and user ID. When a user is identified, all previous anonymous sessions are merged automatically.

Create reusable user segments based on conditions like country, browser, OS, device type, session duration, error count, or URL patterns. Segments support AND/OR logic and can be used in session filters and survey targeting.

Organise sessions into named, colour-coded collections. Add sessions from the session list (multi-select) or from the replay player. Useful for grouping related sessions during bug investigations or UX reviews.

Star any session to add it to your personal favourites list for quick access.

Create rules that fire when thresholds are breached:

• Error Spike: N+ errors within a time window
• New Error: a previously unseen error type appears
• Rage Clicks: N+ rage click sessions in a period
• Slow Vitals: web vital metric exceeds threshold

Notifications can be sent via email, Slack, or webhook.

Send HTTP POST requests to your endpoint when events occur. Available events: new_error, rage_click, session_end, alert_fired. Each webhook includes a secret key for signature verification.

{
  "event": "new_error",
  "project_id": "abc-123",
  "data": {
    "error_type": "TypeError",
    "message": "Cannot read property 'map' of undefined",
    "url": "/dashboard",
    "session_id": "sess-456",
    "session_url": "https://app.webrec.app/..."
  },
  "timestamp": "2025-03-28T10:00:00Z"
}

In Project Settings → Integrations, add your Jira domain, email, API token, and default project key. Issues are created via the Jira REST API.

Add your Linear API key and team ID. Issues are created in the selected team with a link back to the session.

• Check your API key is correct and starts with wr_
• Verify the SDK is loaded: check for [Webrec] messages in the browser console
• Enable debug: true in the config for verbose logging
• Check for ad blockers: use a reverse proxy to avoid this
• Verify sampleRate is not set too low
• Check that respectDoNotTrack isn’t blocking you (some dev browsers have DNT on)
• Ensure minSessionDuration isn’t filtering out your test sessions

If you see CORS errors in the console, set up a reverse proxy to route traffic through your domain. This is the recommended approach for production.

Add api.webrec.app (or your proxy domain) to your script-src and connect-src directives. See the CSP section for details.

Disable recordCanvas, increase sampling.mousemove to 200+, and check if captureNetwork is recording large response bodies. See Sampling & Performance.

This can happen if CSS is loaded from a CDN that blocks cross-origin access. Ensure your stylesheets include crossorigin="anonymous" and your CDN sends Access-Control-Allow-Origin headers. Enabling collectFonts: true (default) also helps with font rendering accuracy.