@bugreels/web-script

DelogX session recording SDK. It captures rrweb snapshots, DOM mutations, console output, network request metadata, runtime errors, and metadata-aware custom tags.

Installation

npm install @bugreels/web-script
# or
yarn add @bugreels/web-script
# or
pnpm add @bugreels/web-script

Quick Start

Use sendMode: "immediate" if you want uploads to start as soon as recording begins.

import { init, startTracking } from "@bugreels/web-script";

init({
  apiKey: "your-api-key",
  ingestUrl: "http://localhost:4000/ingest/batch",
  queryServiceUrl: "http://localhost:4002",
  sendMode: "immediate",
});

startTracking();

If ingestUrl or queryServiceUrl are omitted, the SDK uses the BugReels production defaults.

Buffered Recording

sendMode defaults to "buffered". In buffered mode, the SDK records immediately but defers uploads until you explicitly trigger sending.

import { init, startTracking, triggerRecording } from "@bugreels/web-script";

init({
  apiKey: "your-api-key",
  sendMode: "buffered",
});

startTracking();

document.addEventListener(
  "click",
  () => {
    triggerRecording();
  },
  { once: true },
);

You can also defer start/upload until specific events fire with recordOn.

Configuration

export interface DelogxConfig {
  apiKey: string;
  ingestUrl?: string; // Default: https://bugreels.com/ingest/batch
  queryServiceUrl?: string; // Default: https://bugreels.com/be/be-query
  recordOn?: string[];
  recordOnOptions?: AddEventListenerOptions;
  sendMode?: "immediate" | "buffered";
  rrwebCheckoutEveryNms?: number; // Default: 30000
  captureRedux?: boolean; // Default: false
}

Notes:

• recordOn lets you delay recording until specific browser events fire, for example ["click", "keydown"].
• recordOnOptions is passed directly to window.addEventListener.
• sendMode: "immediate" enables uploads right away. sendMode: "buffered" keeps events local until triggerRecording() fires.
• rrwebCheckoutEveryNms controls how often rrweb takes a fresh full snapshot. Raising it reduces large replay payloads without changing the normal upload batch interval.
• captureRedux: true enables automatic Redux capture through the Redux DevTools hook when the app exposes it.

API

Initialization and Recording

• init(config) initializes the SDK and stores runtime config.
• startTracking() starts recording asynchronously.
• trackAll() is the async form of startTracking().
• startRecording() is an explicit alias for starting recording.
• initSession() creates the session without starting rrweb capture yet.
• stopRecording() pauses recording.
• resumeRecordingManually() resumes a paused recording.
• startRecordingOnEvents(events, options?) starts recording when one of the listed browser events fires.
• createRecordingTrigger() returns a one-shot function that starts recording/uploading only once.
• triggerRecording() starts recording if needed and enables uploads in buffered mode.
• attachReduxStore(store) attaches a plain Redux store directly when the app does not expose the Redux DevTools hook.
• trackReduxStore(store, options?) remains available for explicit debug-oriented Redux tracing.

Session Helpers

• getSessionId() returns the current session id if it is already known.
• getSessionIdAsync() resolves the session id, creating/loading the session first if needed.

User Identification

import { setUserId, getUserId, clearUserId } from "@bugreels/web-script";

setUserId("user-123");
const userId = getUserId();
clearUserId();

getUserId() always returns a string. If you have not called setUserId(), the SDK falls back to a stable anonymous ID in local storage.

Custom Tags

The package exports type CustomTag = { tag: string; meta?: Record<string, unknown> }.

import {
  clearCustomTags,
  getCustomTags,
  setCustomTags,
  type CustomTag,
} from "@bugreels/web-script";

const tags: CustomTag[] = [
  { tag: "premium-user", meta: { plan: "pro" } },
  { tag: "image-compression-failed", meta: { ext: "jpg", taskId: "abc123" } },
];

setCustomTags(tags);
const currentTags = getCustomTags();
clearCustomTags();

Validation and normalization:

• tag values are trimmed and must be non-empty and at most 100 characters.
• Duplicate tag values are deduplicated with latest value winning.
• At most 50 tags are kept.
• meta must be a plain JSON-serializable object; invalid values are normalized to {}.
• Writes are serialized through an internal queue so setCustomTags() / clearCustomTags() calls are persisted in order.

Framework Integration

React

import { useEffect } from "react";
import { init, startTracking } from "@bugreels/web-script";

export function App() {
  useEffect(() => {
    init({
      apiKey: import.meta.env.VITE_DELOGX_API_KEY,
      ingestUrl: import.meta.env.VITE_DELOGX_INGEST_URL,
      queryServiceUrl: import.meta.env.VITE_DELOGX_QUERY_URL,
      sendMode: "immediate",
    });
    startTracking();
  }, []);

  return <div>Your App</div>;
}

Next.js

"use client";

import { useEffect } from "react";
import { init, startTracking } from "@bugreels/web-script";

export function DelogxProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({
      apiKey: process.env.NEXT_PUBLIC_DELOGX_API_KEY!,
      ingestUrl: process.env.NEXT_PUBLIC_DELOGX_INGEST_URL,
      queryServiceUrl: process.env.NEXT_PUBLIC_DELOGX_QUERY_URL,
      sendMode: "immediate",
    });
    startTracking();
  }, []);

  return children;
}

Vanilla JS

<script src="/path/to/index.global.js"></script>
<script>
  DelogX.init({
    apiKey: "your-api-key",
    ingestUrl: "http://localhost:4000/ingest/batch",
    queryServiceUrl: "http://localhost:4002",
    sendMode: "immediate",
  });
  DelogX.startTracking();
</script>

What Gets Recorded

• DOM snapshots and mutations via rrweb
• User interactions such as clicks, scrolls, and inputs
• Console logs (log, info, warn, error)
• Network request metadata such as method, URL, status, and timing
• Redux action/state traces when captureRedux: true is enabled or the store is attached directly
• JavaScript errors and unhandled promise rejections

Privacy and Security Notes

• Sensitive headers are filtered before persistence.
• SDK auth uses an API-key exchange at /auth/token to obtain a short-lived WebSocket token.

Local Debug Logging

Set DEBUG_MODE=true in packages/web-script/.env before building to enable verbose browser-side logs.

License

MIT