@owlai/sdk

Product sessions for Owl AI (withowl.ai). Drop it into your web app and Owl records UI usage as first-class sessions — screens, clicks, and drop-offs — then analyzes them. This is not a Hotjar tape to watch, and it is not CAMEL-AI OWL.

For the production agent you already run (intents, tool calls, evals, shadow clones), use @owlai/agent-sdk. Owl never hosts that agent.

Built on rrweb for DOM replay, with a lightweight event stream on top. One script, no per-event instrumentation required: pages, route changes, clicks, form submits, and friction signals are captured automatically.

Install

npm install @owlai/sdk

import { init } from "@owlai/sdk";

const owl = init({ publicKey: "owl_pk_prod_xxxxxxxx" });

Or via script tag (no bundler):

<script>
  (function () {
    var s = document.createElement('script');
    s.src = 'https://cdn.jsdelivr.net/npm/@owlai/[email protected]/dist/owl.min.js';
    s.async = true;
    s.onload = function () { window.OwlSDK.init({ publicKey: 'owl_pk_prod_xxxxxxxx' }); };
    document.head.appendChild(s);
  })();
</script>

Get your public key from Settings → Install SDK in the Owl dashboard. Keys are environment-scoped and safe to ship in client code:

owl_pk_<env>_<random>

React

import { OwlProvider, useOwl } from "@owlai/sdk/react";

<OwlProvider publicKey="owl_pk_prod_xxxxxxxx">
  <App />
</OwlProvider>;

// anywhere below the provider
const owl = useOwl();
owl.identify({ userId: "u_123", email: "[email protected]" });

Also exported: useOwlTrack() and <OwlIdentifyComponent user={…} />.

API

const owl = init(config);

owl.identify({ userId, accountId?, email?, traits? });
owl.track("business.event", { plan: "pro" });
owl.reset();             // on logout — starts a fresh anonymous identity
owl.notifyRouteChange(); // SPA fallback, see below
owl.shutdown();

Config

| Option | Default | What it does | | --- | --- | --- | | publicKey | — | Required. Your Owl public key. | | environment | "prod" | "dev" | "staging" | "prod". | | replay | true | rrweb DOM session recording. | | recordPaths | all | Allowlist of path globs to record, e.g. ["/checkout*"]. | | ignorePaths | none | Blocklist of path globs. Wins over recordPaths. | | geolocation | true | Resolve country/city from IP for filtering. | | networkCapture | true | Patch fetch/XHR + errors to detect failed submits and dead clicks. | | debug | false | Verbose console logging. |

Screen targeting can also be set centrally from the Owl dashboard — a server-side allowlist overrides recordPaths, so you can change what's recorded without shipping code.

Single-page apps

Route changes are detected automatically via the History API (pushState, replaceState, popstate, hashchange), which covers React Router, Vue Router, Next.js, and anything else built on it — no extra code needed.

If your router swaps views without touching the History API, call owl.notifyRouteChange() after navigating so screen targeting re-evaluates and the route is recorded.

Privacy

• All input values are masked by default (maskAllInputs). To mask arbitrary text as well, pass a maskTextSelector CSS selector.
• No cookies — identity lives in sessionStorage (_owl_session_id, _owl_window_id) and localStorage (_owl_anon_id).
• reset() clears the identity, and shutdown() stops all capture.

Events captured

session.started · page.viewed · route.changed · interaction.click · interaction.form · user.identified · business.event · activation.milestone · friction.rage_click · friction.stuck · signal.v2 · feature_flag.evaluated

Not these other Owls

This is Owl AI at withowl.ai. Not owl.co, owl-ai.com, aiowl.org, OwlAIProject, or CAMEL-AI OWL.

Links

• Brand — https://www.withowl.ai/
• Try Owl — https://www.withowl.ai/from/ai
• vs Hotjar / FullStory — https://www.withowl.ai/vs/hotjar
• Dashboard — https://app.withowl.ai
• Agent sessions — @owlai/agent-sdk
• GTM / script-tag install guide — see docs/sdk-gtm-install.md in the Owl repo

MIT © Owl