@owlsdks/owl

Owl session recording SDK — rrweb-based session replay + product events, streamed to Owl for automatic friction detection (rage clicks, dead clicks, form errors, stuck states) and insight generation.

• Ships ESM + CJS builds with type declarations.
• React bindings under @owlsdks/owl/react (React is an optional peer dependency — only pulled in if you use them).
• A standalone browser bundle (window.OwlSDK) for <script> / CDN usage.

Installation

npm install @owlsdks/owl
# or
pnpm add @owlsdks/owl
# or
yarn add @owlsdks/owl

You'll need an Owl public key (owl_pk_...), issued per company from the Owl app's "Install Owl SDK" screen.

Quick start (vanilla JS/TS)

import { init } from "@owlsdks/owl";

const owl = init({
  publicKey: "owl_pk_...",
  environment: "prod",
  replay: true, // enable rrweb session replay
  endpoint: "https://your-owl-backend/api/v1/sdk/recordings/ingest",
});

owl.identify({ userId: "u_123", email: "[email protected]" });
owl.track("activation.milestone", { type: "first_value" });

React / Next.js

import { OwlProvider } from "@owlsdks/owl/react";

export function App({ children }: { children: React.ReactNode }) {
  return (
    <OwlProvider
      publicKey="owl_pk_..."
      environment="prod"
      replay
      endpoint="https://your-owl-backend/api/v1/sdk/recordings/ingest"
    >
      {children}
    </OwlProvider>
  );
}

import { useOwl, useOwlTrack } from "@owlsdks/owl/react";

function CheckoutButton() {
  const owl = useOwl();
  const track = useOwlTrack();
  // owl.identify({ userId, accountId }) right after auth resolves
  return <button onClick={() => track("business.event", { name: "checkout" })}>Buy</button>;
}

Script tag (no bundler)

<script src="https://unpkg.com/@owlsdks/owl/dist/owl.min.js"></script>
<script>
  const owl = OwlSDK.init({
    publicKey: "owl_pk_...",
    replay: true,
    endpoint: "https://your-owl-backend/api/v1/sdk/recordings/ingest",
  });
</script>

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | publicKey | string | — | Required. Must start with owl_pk_. | | environment | "dev" \| "staging" \| "prod" | "prod" | Reported with each batch. | | replay | boolean | false | Enable rrweb DOM/session-replay capture. | | endpoint | string | https://api.owla.dev/sdk/recordings/ingest | Replay ingest URL. Point this at your Owl backend (.../api/v1/sdk/recordings/ingest). | | apiBaseUrl | string | https://app.withowl.ai/api/sdk | Product-events base URL. | | debug | boolean | false | Log SDK activity to the console. | | maskAllInputs | boolean | true | Mask all input values in the replay. | | maskTextSelector | string \| null | null | CSS selector for text to mask. | | blockSelector | string | [data-owl-ignore] | CSS selector for elements to omit from the replay. | | sampleRate | number | 1.0 | Fraction of sessions to record (0–1). |

Note: the default endpoint/apiBaseUrl point at Owl-hosted infrastructure. If you run your own Owl backend, set endpoint to https://<your-host>/api/v1/sdk/recordings/ingest, and make sure that backend's CORS allows your site's origin.

Client API

init(config) returns:

• identify(user) — { userId, accountId?, email?, traits? }
• track(event, properties?) — emit a product event
• reset() — clear identity and start a fresh session
• shutdown() — flush and stop recording

License

MIT