webagent-sdk

The WebAgent AI browser SDK — silently observes user behaviour and turns it into plain-English business insights.

Zero runtime dependencies. < 35 KB gzip. Never blocks the host page.

Install

npm install webagent-sdk
# or
pnpm add webagent-sdk
# or
yarn add webagent-sdk

Or via CDN (drop-in snippet, no build step — served from jsDelivr):

<script src="https://cdn.jsdelivr.net/npm/webagent-sdk/dist/webagent.iife.js"></script>
<script>
  WebAgent.init({ apiKey: "wa_live_xxxxxx" });
</script>

Usage

One function call activates everything:

import { init } from "webagent-sdk";

init({ apiKey: "wa_live_xxxxxx" });

Custom events

const webagent = init({ apiKey: "wa_live_xxxxxx" });

webagent.track("video_started", { title: "Product tour", duration: 45 });

GDPR / cookie consent

// When consentRequired is set, nothing is sent until consent is granted.
init({ apiKey: "wa_live_xxxxxx", consentRequired: true });

// From your consent banner:
webagent.setConsent(true); // or false to revoke

Options

| Option | Type | Default | Description | | ----------------- | --------- | --------------------------------- | -------------------------------------------------- | | apiKey | string | — (required) | Site-scoped live key (wa_live_...) | | endpoint | string | https://collect.webagent.ai/v1 | Collector base URL | | enabled | boolean | true | Master kill-switch | | consentRequired | boolean | false | GDPR mode — waits for setConsent(true) | | sampleRate | number | 1 | 0..1 traffic sampling | | maskIdentity | boolean | false | Skip UA parsing | | maskPaths | boolean | false | Strip URLs/paths from payloads | | disabledTrackers| object | {} | Disable specific trackers by event type | | flushIntervalMs | number | 5000 | Batch flush interval |

What is tracked automatically

Page views · SPA route changes · clicks · link clicks · rage clicks · dead clicks · scroll depth · mouse heatmap · form submits · copy/paste · keystroke volume · time on page · exit intent · visibility changes · JS errors · console errors · unhandled rejections · network failures · Core Web Vitals (LCP, CLS, INP, FCP, TTFB) · slow resources · custom events.

Privacy & performance

• No cookies are set by the SDK; identity uses localStorage/sessionStorage only.
• Events are batched (≤ 10 KB) and flushed with sendBeacon during pagehide so nothing is lost when the tab closes.
• Mouse movement is sampled at 5 Hz into a bounded ring buffer; heatmaps ship once per page view.
• Every browser API call is defensive — the SDK cannot crash or block the host page.

Development

pnpm --filter webagent-sdk build   # ESM + CJS + IIFE
pnpm --filter webagent-sdk test    # vitest
pnpm --filter webagent-sdk check-size  # enforces the 35 KB gzip budget