@obsunified/analytics-sdk

Browser analytics SDK for obs-unified. Captures usage events, mints click-scoped interaction_id correlation keys, injects them on outbound fetch/XHR, and (optionally) records rrweb session replay chunks.

pnpm add @obsunified/analytics-sdk

React

import {
  AnalyticsProvider,
  AnalyticsErrorBoundary,
} from "@obsunified/analytics-sdk/react";

createRoot(document.getElementById("root")!).render(
  <AnalyticsProvider
    collectorUrl={import.meta.env.VITE_OBS_COLLECTOR_URL}
    apiKey={import.meta.env.VITE_OBS_INGEST_KEY}
    trackPageViews
    captureErrors
  >
    <AnalyticsErrorBoundary context="App">
      <App />
    </AnalyticsErrorBoundary>
  </AnalyticsProvider>,
);

The provider installs Mode A auto-correlation: every click / submit / keydown mints an interaction_id and window.fetch is patched to add the x-obs-interaction header on outbound requests. No per-button wiring needed for the happy path.

Vanilla / non-React

import { installAutoCorrelate, UsageTracker } from "@obsunified/analytics-sdk";

const tracker = new UsageTracker({
  collectorUrl: "https://obs.my-app.com",
  apiKey: "...",
});

installAutoCorrelate({ tracker });

Mode B — manual interaction context

For async work that escapes the microtask cascade (debounce, setTimeout, state machines), capture and re-enter explicitly:

import {
  currentInteractionId,
  withInteractionContext,
} from "@obsunified/analytics-sdk";

const id = currentInteractionId();
setTimeout(() => {
  withInteractionContext(id!, () => {
    fetch("/api/long-running"); // carries the click's interaction_id
  });
}, 500);

Identity propagation

The interaction key flows: browser click → x-obs-interaction header → server stamps it onto the root span → every child span / log / AI call in that request inherits it. See docs/spec/interaction-id.md for the wire spec.

Full docs

https://obs-unified-docs.dev (or the obs-unified-docs repo for self-hosting).