Web SDK

Record pixel-accurate session replays, track product events, and capture every JavaScript error from any web app — with a few lines of code.

Install

npm install @replayfyapp/browser

<!-- Async, non-blocking loader — exposes a global `Replayfy` and queues
     init/track calls until the self-contained bundle arrives. -->
<script>
  !(function () {
    var r = (window.Replayfy = window.Replayfy || []);
    ['init', 'identify', 'track', 'captureException', 'flush', 'stop'].forEach(function (m) {
      r[m] = function () { r.push([m].concat([].slice.call(arguments))); };
    });
    var s = document.createElement('script');
    s.async = true;
    s.crossOrigin = 'anonymous';
    s.src = 'https://cdn.replayfy.app/v1/replay.global.js';
    var f = document.getElementsByTagName('script')[0];
    f.parentNode.insertBefore(s, f);
  })();
</script>

Initialize

Start recording

Call the initializer as early as possible — recording begins immediately. Only apiKey and apiHost are required.

import { initReplay } from "@replayfyapp/browser";

const replay = initReplay({
  apiKey: "rpl_pk_YOUR_KEY",
  apiHost: "https://us.replayfy.app",  // or your self-hosted API URL
});

<!-- The async loader from the Install step already put `Replayfy` on the page
     and queues this call until the bundle is ready. -->
<script>
  Replayfy.init({
    apiKey: "rpl_pk_YOUR_KEY",
    apiHost: "https://us.replayfy.app",  // or your self-hosted API URL
  });
</script>

init() is idempotent — a second call returns the live session instead of starting a second recording.

Why the loader looks like this. Loading the bundle with async means it never blocks your page from rendering, and the small inline stub queues any init/track calls made before the bundle finishes downloading (they replay in order once it does). The crossorigin="anonymous" attribute is what lets the browser hand Replayfy a full error stack trace instead of a bare "Script error." — without it, the browser’s cross-origin security model strips the message, file, and stack from any error thrown by a script served from another origin (the CDN). Replayfy’s CDN sends the matching Access-Control-Allow-Origin header, so the two work together. If you self-host the bundle on a host that does not send that header, drop the crossorigin line — otherwise the browser will refuse to load the script.

Identify the user (optional)

Attach a distinct id and traits so replays and events are tied to a real person.

replay.identify("user_123", { email: "[email protected]", plan: "pro" });
replay.track("checkout_started");

Replayfy.identify("user_123", { email: "[email protected]", plan: "pro" });
Replayfy.track("checkout_started");

Include picture (or its alias avatar) with a public https image URL — either top-level or inside customProps — to set the user’s avatar in the recording header and Users list; non-URL values are ignored. With the script tag you call these on the Replayfy global (no returned controller to hold).

React / Next.js — call initReplay(...) once in a top-level client effect (e.g. a root useEffect or a "use client" provider) so it runs in the browser, not during server rendering. The single instance persists across route changes.

Verify

Reload your app, click around for a few seconds, then open the Sessions view in your Replayfy dashboard — your first session appears within a minute.

Configuration

Pass these options to initReplay(config) (npm) or Replayfy.init(config) (CDN). Only apiKey and apiHost are required.

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your project’s publishable API key.
`apiHost`	`string`	—	Required. Replayfy ingest host, e.g. `https://us.replayfy.app` (or your self-hosted API URL).
`projectId`	`string`	—	Optional project identifier, useful when one key spans environments.
`distinctId`	`string`	—	Identify the user at startup (equivalent to calling `identify` immediately).
`revId`	`string`	—	Build / release id of the deployed app, to scope replays and funnels to one release.
`sessionId`	`string`	auto	Override the generated session id (advanced; normally left unset).
`flushIntervalMs`	`number`	`3000`	How often, in milliseconds, buffered events are sent.
`maxBufferSize`	`number`	—	Maximum number of events to hold in memory between flushes.
`captureConsole`	`boolean`	`true`	Record `console.*` output on the session timeline.
`captureNetwork`	`boolean`	`true`	Record fetch/XHR requests (method, URL, status, timing).
`captureErrors`	`boolean`	`true`	Capture unhandled errors and promise rejections.
`captureHeaders`	`boolean`	`false`	Include request/response headers on captured network events.
`redactHeaderNames`	`string[]`	—	Extra header names (beyond the built-in deny-list) whose values are masked before sending.
`maxBodyBytes`	`number`	`8192`	Maximum captured request/response body size, in bytes.
`captureResourceTimings`	`boolean`	`true`	Capture per-resource timing (images, scripts, CSS, fonts).
`resourceMinDurationMs`	`number`	`0`	Skip resource-timing entries faster than this many milliseconds to trim volume.
`maskAllInputs`	`boolean`	`true`	Mask the value of every `<input>` in the replay.
`maskTextSelector`	`string`	—	CSS selector for text nodes to mask in the replay.
`blockSelector`	`string`	—	CSS selector for elements to fully block (rendered as a placeholder).
`redactUrls`	`Array<string \| RegExp>`	—	Patterns whose matches are stripped from captured URLs.
`excludeUrls`	`string[]`	—	“Don’t record this page” — a deny-list of URL path globs (`` matches within a path segment, `` matches across segments), e.g. `["/settings/billing", "/admin/*"]`. A matching page records nothing and ships nothing.
`sdk`	`object`	—	Override SDK descriptor fields (name/version) reported with each batch.
`beforeSend`	`(event) => event \| null`	—	Inspect or mutate each batch before it’s sent; return `null` to drop it.
`fetchImpl`	`typeof fetch`	`window.fetch`	Custom `fetch` implementation (advanced/testing).

Privacy, capture, and sampling settings configured in your Replayfy dashboard are fetched at startup and take precedence over the values passed to init() — so you can tighten masking or pause recording without shipping a new build.

Auto-captured clicks are now labelled with the element’s real text — its aria-label, title, associated form-control label, or trimmed visible caption — instead of a raw CSS selector, so heatmaps and click funnels read as human-friendly names (an input’s typed value is never used as a label).

API reference

initReplay() returns a controller with the methods below. With the CDN global, the same methods are available as Replayfy.identify(...), Replayfy.track(...), etc., after Replayfy.init(...).

Method	Signature	Description
`identify`	`identify(distinctId: string, props?: object): void`	Associate the current session with a user. Also accepts a single payload object: `identify({ distinctId, ...traits })`.
`track`	`track(name: string, properties?: object): void`	Record a custom product event. Use stable `snake_case`/`camelCase` names so they’re searchable in funnels.
`captureException`	`captureException(error: Error, opts?: { handled?: boolean }): void`	Report a handled exception as a first-class issue (name, message, parsed stack). `opts.handled` defaults to `true`; pass `false` to record a fatal error.
`flush`	`flush(): Promise<void>`	Send any buffered events immediately.
`stop`	`stop(): Promise<void>`	Stop all capture, end the session, and flush the final batch.
`sessionId`	`sessionId: string`	The current session’s id, handy for correlating with your own logs.
`urlForCurrentSession`	`urlForCurrentSession(): string \| null`	The dashboard deep link for the current session — `<app-host>/recordings/<id>`, with the app host derived from `apiHost`. Returns `null` before a session has started. This is the private, authenticated dashboard view, not a public share link.

// handled error
try {
  risky();
} catch (e) {
  replay.captureException(e);
}

// fatal error
replay.captureException(new Error("boom"), { handled: false });

await replay.flush();
await replay.stop();
console.log(replay.sessionId);
console.log(replay.urlForCurrentSession()); // → https://app.replayfy.app/recordings/<id> (or null)

// handled error
try {
  risky();
} catch (e) {
  Replayfy.captureException(e);
}

// fatal error
Replayfy.captureException(new Error("boom"), { handled: false });

await Replayfy.flush();
await Replayfy.stop();
console.log(Replayfy.sessionId);
console.log(Replayfy.urlForCurrentSession()); // → https://app.replayfy.app/recordings/<id> (or null)

Privacy & masking

Replayfy is designed to keep sensitive data in the browser — every <input> value is masked by default. Tune redaction with these options:

maskAllInputs (default true) — masks the value of every input field in the replay.
maskTextSelector — CSS selector for text nodes to mask (e.g. .pii, .account-number), shown as ●●●● in playback.
blockSelector — CSS selector for elements to block entirely; they render as a placeholder box.
redactUrls — string/RegExp patterns stripped from captured URLs, so tokens and ids never leave the page.
excludeUrls — path globs for whole pages that must never be recorded (e.g. ["/settings/billing", "/admin/**"]); a matching page captures and ships nothing at all.
captureHeaders (default false) — headers are only captured when explicitly enabled.
redactHeaderNames — additional header names whose values are masked, on top of the always-on built-in deny-list.
maxBodyBytes — caps how much of a request/response body is ever captured.

<!-- inputs are masked automatically -->
<input type="text" name="ssn" />

<!-- mask the TEXT of an element -->
<span class="rpf-mask">4111 1111 1111 1111</span>

<!-- BLOCK an element entirely -->
<div class="rpf-block"><!-- third-party chat widget --></div>

initReplay({
  apiKey: "rpl_pk_YOUR_KEY",
  apiHost: "https://us.replayfy.app",  // or your self-hosted API URL
  maskAllInputs: true,
  maskTextSelector: ".rpf-mask",
  blockSelector: ".rpf-block",
  redactUrls: [/\/reset-password\/[^/]+/],
});

Replayfy.init({
  apiKey: "rpl_pk_YOUR_KEY",
  apiHost: "https://us.replayfy.app",  // or your self-hosted API URL
  maskAllInputs: true,
  maskTextSelector: ".rpf-mask",
  blockSelector: ".rpf-block",
  redactUrls: [/\/reset-password\/[^/]+/],
});

For full control, beforeSend receives each batch before it leaves the browser, so you can drop or scrub anything programmatically.

Identify users

Tie sessions and events to real people with distinct ids and traits.

Track events

Fire custom product events to power funnels, segments, and retention.

Privacy & masking

Redact inputs, text, elements, and URLs before data leaves the browser.

Get started

Self-hosting

Install the SDK

Products

Platform

Guides

Help

Install

Initialize

Verify

Configuration

API reference

Privacy & masking

Identify users

Track events

Privacy & masking

​Install

​Initialize

​Verify

​Configuration

​API reference

​Privacy & masking

Identify users

Track events

Privacy & masking

Install

Initialize

Verify

Configuration

API reference

Privacy & masking