Web SDK

Add the dependency, call start() once, and the signals below arrive on their own. There is no event taxonomy to design first and no tracking plan to keep up to date.

Published on npm · drengr-js.

Before you start

Requirements for the Web SDK
Runtime	Any browser with fetch and localStorage. Ships ESM and CommonJS with TypeScript types.
Permissions	None. Runs client-side only.
Publishable key	Console, under Settings. It is a publishable key, safe to ship in client code: it can only append events.

Install

bash

npm install drengr-js

Start it

In your app entry (or a root layout). Your publishable key is safe to ship in client code: it can only write.

your app entry (or a root layout)ts

// npm install drengr-js
import { Drengr } from 'drengr-js';

Drengr.start({
  ingestUrl: 'https://ziryfxrwrvnunwjupgfg.supabase.co/functions/v1/ingest',
  publishableKey: 'drengr_pk_YOUR_KEY',
  appPackage: 'com.example.myapp',
});

What arrives on its own

You do not instrument these. They are captured from the moment start() runs. The third column names the Web API behind each one, so you can check the claim against your own app.

Signals the Web SDK captures automatically, and the platform hook behind each
Signal	What it records	Where it comes from
screen_view	Every screen or route the user lands on	A History API patch on pushState and replaceState, plus popstate, hashchange and the initial load
tap	Taps, with the element's own label when it has one	A capture-phase click listener on document
net / net_fail	Outgoing requests: host, path, status, duration, size	A fetch wrapper plus XMLHttpRequest.prototype.open and send
crash	Uncaught exceptions with their stack	window error and unhandledrejection listeners
rage_tap / dead_tap	Repeated taps that did nothing — the friction signal	The same capture-phase click listener as tap
rage_scroll / dead_scroll	Scroll thrash and scrolls that moved nothing	A passive capture-phase wheel listener on document
app_foreground / app_background	Lifecycle, which is what sessions are built from	visibilitychange and pagehide
identify	Your own user id, when you choose to send one	Your own call to identify()

fetch and XMLHttpRequest are both wrapped, so requests are captured regardless of which your app uses.

History routing is followed automatically — single-page navigations register as screen views.

Runs client-side only. In Next.js, call start() from a client component.

What never leaves the device

Emails, phone numbers, card numbers and government ids are detected and sealed on the device before the first byte is sent. Our servers hold ciphertext they cannot open. Labels and URLs are redacted and length-capped on the device too.

And what is never collected in the first place:

What the Drengr SDKs do not collect, and why that is structural
Not collected	How you can tell
Screen recordings, screenshots or DOM snapshots	There is no column for pixels or markup on the events table, and no SDK reads the framebuffer.
Keystrokes	Tap capture records that a tap happened and the element's own accessibility label. No SDK attaches a key or text listener.
Raw request and response bodies	What is stored is a safe dotted-path projection, redacted and capped at 64 KiB on the device before anything is sent.
Authorization headers, cookies and API keys	Masked by name before capture, along with password, pin, cvv, ssn, otp and iban field names.
An IP address on the event	The events table has no ip or geo column, so no stored event carries one.
Advertising or cross-app identifiers	Identity is a random install_id the SDK generates. No IDFA, no GAID, and no device fingerprint is used for identity.

Most autocapture tools promise not to look. This is built so we cannot. Full design in Security and Privacy.

Start paused behind a consent gate with start({ enabled: false }), then resume once the user agrees. A persisted opt-out always wins over that argument, so an opted-out install stays paused across restarts.

Consent controls on the Web SDK
Start paused	start({ enabled: false })
Opt out	optOut()
Opt back in	optIn()
Where the choice is stored	localStorage, key drengr_opt_out

Retention, deletion and what a GDPR or CCPA request maps to are on Privacy controls.

Check it worked

Run the app and use it for a few seconds, then open the console. Overview checks for your first event every 15 seconds on its own, so you do not need to keep reloading.

Nothing showing up

The first five happen on every platform. The rest are specific to Web.

Failure modes on the Web SDK, with the cause and the fix
What you see	Why	Fix
No events at all, and Overview never leaves its empty state	The key belongs to a different organisation, so the writes are accepted against a tenant you are not looking at.	Copy the key again from Settings in the organisation you have open in the console.
Events exist but your app is missing from the picker	app_package does not match the scope you are viewing.	Use your real bundle or package id, the same string on every launch. A display name will create a second app.
Events appear only after you close the app	Not a bug. The queue batches in memory and flushes on background, which is what makes a dropped connection free.	Background the app once, or wait for the next flush. Nothing is lost in the meantime.
Screens are empty but taps and network arrive	Screen capture is the one signal that can be wired separately from start().	Check the screen hook for your platform in the table above.
Nothing arrives after a user opted out	Working as intended. A persisted opt-out outranks the start argument and survives restarts.	Call the opt-in method for your platform. See Privacy controls.
Nothing captured, and the console shows a server-render error	start() touches window and localStorage, so it cannot run on the server.	Call it from a client component. In Next.js that means a file with the "use client" directive.
An opted-out visitor still emitted one event on load	You supplied an async storage adapter, so the opt-out check resolves after start() returns.	Use synchronous storage (the default localStorage path) and the check runs before any capture begins.

Where to go next

Once events are arriving, these are the things worth doing, in order.

Wire up consent and opt-outThe gate, the persisted opt-out, the 180-day window and the deletion call.
Take the event inventory as JSONThe same signals, hooks and exclusions as a machine-readable contract for your pipeline or review.
Bring in what you already havePoint an existing Amplitude or Segment pipe at us, or import your history.
Drengr ActuatorThe separate MCP server that gives an agent eyes and hands on a real device.

Not ready to install anything?

Drop a .har of traffic you already have and see the business events your current analytics is missing. It runs in your browser; nothing is uploaded.

Scan for blind spots →