Browser SDK

The browser SDK (@sazabi/browser) instruments a web frontend and sends telemetry to Sazabi. It captures errors, navigation, clicks, network calls, and console output, and lets you emit custom events and logs. It authenticates with a public key, which is write-only and safe to ship in your bundle.

For server-side reads and writes against the API, use the TypeScript SDK with a secret key instead.

Install

npm install @sazabi/browser

Initialize

Import the register entrypoint first — before any other import — so the SDK installs its instrumentation before other code captures the native fetch, XMLHttpRequest, or history APIs. Then call init:

import "@sazabi/browser/register";
import { init } from "@sazabi/browser";

init({
  intakeUrl: import.meta.env.VITE_SAZABI_INTAKE_URL,
  serviceName: "my-web-app",
});

init is idempotent. init options:

Get the public key from Settings > Public keys. Never use a secret key in the browser.

Identify and reset

import { identify, reset } from "@sazabi/browser";

// After sign-in:
identify("user_123", { plan: "pro" });

// On sign-out:
reset();

identify attaches a client-asserted user identity (and optional traits) to subsequent events. reset clears the identity and rotates the session so a shared device does not thread activity into the previous user's timeline.

Custom events and logs

import { addEvent, log } from "@sazabi/browser";

addEvent("checkout_started", { cartValue: 42 });
log("WARN", "cache lookup failed", { requestId: "req_9" });

addEvent(name, attributes?) emits a custom event into the session stream. log(severity, message, metadata?) emits an application log line with session context; severity is one of DEBUG, INFO, WARN, or ERROR.

Flush and shutdown

import { flush, shutdown } from "@sazabi/browser";

await flush(); // Force-send queued events now.
await shutdown(); // Flush, then remove all instrumentation.

flush sends any queued events immediately. shutdown flushes and removes the SDK's instrumentation, reversing init and the register import.

What the SDK captures automatically

After init, the SDK captures, with session context attached:

• Errors — uncaught exceptions and unhandled promise rejections, with stack traces.
• Navigation — page loads and single-page-app route changes.
• Clicks — interactions on interactive elements, by privacy-safe selector and label. It also flags rapid repeat clicks and clicks with no response.
• Input interactions — one event per field engagement (by field label). It never captures keystrokes or values.
• Network calls — fetch and XMLHttpRequest calls with method, status, and duration. By default it injects a W3C traceparent header on same-origin requests so frontend and backend telemetry correlate.
• Console — mirrors console.error and console.warn by default (the original console output is untouched).

The SDK never captures request or response bodies, input values, or keystrokes. Mark an element subtree with data-sazabi-mask to suppress its text capture.

Further reading