EchoDom Browser SDK

Session replay + RUM telemetry for the EchoDom ingestion backend.

Install

npm i @echodom/sdk

Quickstart

import EchoDom from '@echodom/sdk';

EchoDom.init({
  projectId: '<your-project-id>',
  endpoint: 'https://your-ingest-host/v1/ingest',
});

If you prefer named exports:

import { init, flush, shutdown, getSessionId } from '@echodom/sdk';

init({
  projectId: '<your-project-id>',
  endpoint: 'https://your-ingest-host/v1/ingest',
});

console.log(getSessionId());
// flush();
// shutdown();

Configuration

TrackerConfig

• projectId (required): Project UUID from your EchoDom backend.
• endpoint (required): Ingestion endpoint URL (typically .../v1/ingest). Trailing slashes are removed.
• batchInterval (optional): Flush interval in milliseconds. Default: 5000.
• captureErrors (optional): Capture window.onerror and unhandled promise rejections. Default: true.
• maskClasses (optional): CSS class names to treat as sensitive. Default: [].
• sampleRate (optional): (0.0–1.0). Default: 1.0.
  • If a session is not sampled, init() returns early and the SDK stays inactive.

API

• init(config): Starts the SDK (idempotent). If called again while running, the previous session is shut down first. On init, the SDK starts buffering/sending events and begins rrweb recording.
• flush(): Immediately flushes any buffered events.
• shutdown(): Stops recording/observers, flushes remaining events, and removes hooks.
• getSessionId(): Returns the current session id, or null if the SDK is inactive.

Privacy / masking

maskClasses is passed through to rrweb so content is masked for elements matching those classes.

Example:

EchoDom.init({
  projectId: '<your-project-id>',
  endpoint: 'https://your-ingest-host/v1/ingest',
  maskClasses: ['password', 'secret', 'pii'],
});

Network behavior

Events are batched and sent best-effort:

• Uses navigator.sendBeacon() when available (preferred for unload safety)
• Falls back to fetch(..., { keepalive: true })

Local demo

From sdk/:

npm install
npm run serve

This serves sdk/examples/index.html, which imports the SDK and can send events to a local ingest server (default example endpoint is http://localhost:8080/v1/ingest).

Release / publishing

From sdk/:

npm version patch   # or minor/major
npm publish

npm publish will run prepublishOnly (clean, build, test) before publishing.