🐾 Cerbero

Cerbero is a lightweight TypeScript library for tracking user interactions in the browser. It collects clicks, scrolls, text selections, mouse exits, time on page, performance metrics, Web Vitals, and many more signals — and offloads all processing to a Web Worker so the main thread stays free.

→ Live Demo — see every event type and every plugin in action.

Install

npm install cerbero
# or
yarn add cerbero

CDN (UMD, no bundler needed):

<script src="https://unpkg.com/cerbero/dist/cerbero.umd.js"></script>
<!-- window.cerbero.Cerbero is now available -->

Quick Start

import { Cerbero } from 'cerbero';

const cerbero = new Cerbero();

cerbero.addEventListener((event) => {
  console.log(event.type, event.data);
});

Constructor Options

new Cerbero(config?: CerberoConfig)

Option	Type	Default	Description
`events`	`string[]`	(all)	Whitelist of event types to track. Omit to track everything.
`domPath`	`boolean`	`false`	Include full DOM ancestor path in serialized elements (e.g. `> html > body > div > button`). Results are cached per-element via WeakMap.
`domPosition`	`boolean`	`false`	Include element bounding box via `getBoundingClientRect()`. Forces a synchronous layout reflow on every event.
`batchSize`	`number`	—	Flush callback when N events have accumulated.
`batchInterval`	`number`	—	Flush callback every N milliseconds.

const cerbero = new Cerbero({
  events: ['click', 'scroll', 'webVitals'],
  domPath: true,
  batchSize: 10,
});

Public API

`addEventListener(callback)`

Register the callback that receives every event (or batch).

cerbero.addEventListener((event) => {
  // event is a single object (or unknown[] if batching is enabled)
  sendToMyBackend(event);
});

`setTimeInPageInterval(ms)`

Change how often the timeInPage event fires. Default: 2500 ms.

cerbero.setTimeInPageInterval(5000);

`observeElements(selector)`

Track element visibility via IntersectionObserver. Fires an elementVisible event when a matching element is ≥50% in the viewport.

cerbero.observeElements('.hero-cta, .pricing-card');

`use(plugin)`

Register a plugin that emits custom events through the Cerbero pipeline. Returns this for chaining.

import { fingerprintPlugin } from './plugins/fingerprint';

cerbero.use(fingerprintPlugin());

`destroy()`

Remove all event listeners, disconnect observers, clear intervals, and terminate the Web Worker.

cerbero.destroy();

Event Reference

All events share a base shape:

{
  "type": "click",
  "time": 1720000000000,
  "after": 1234,
  "data": { ... }
}

time — Unix timestamp (ms) when the event was processed
after — ms elapsed since page load
data — event-specific payload

`click`

Fires on every pointer-up (pointerup event, capturing mouse, touch, and pen input).

{
  "type": "click",
  "data": {
    "position": { "screenX": 752, "screenY": 244, "clientX": 752, "clientY": 164,
                  "pageX": 752, "pageY": 3609, "x": 752, "y": 164,
                  "offsetX": 388, "offsetY": 414 },
    "keys": { "ctrlKey": false, "shiftKey": false, "altKey": false, "metaKey": false },
    "pointerType": "mouse",
    "elements": {
      "target": { "id": "", "type": "BUTTON", "domType": "HTMLButtonElement",
                  "identifier": "button#submit", "className": "btn-primary" }
    }
  }
}

`rageClick`

Fires when the same element is clicked 3+ times within 500 ms.

{
  "type": "rageClick",
  "data": {
    "count": 4,
    "target": { "identifier": "button#submit", "domType": "HTMLButtonElement" }
  }
}

`scroll`

Fires once per scroll stop (debounced at 100 ms).

{
  "type": "scroll",
  "data": {
    "scroll": { "fromTop": 1240, "domHeight": 5800, "percentage": 21.37 }
  }
}

`mouseExit`

Fires when the pointer leaves the browser window.

{
  "type": "mouseExit",
  "data": {
    "position": { "screenX": 744, "screenY": 0, "clientX": 744, "clientY": 0,
                  "pageX": 744, "pageY": 820, "x": 744, "y": 0 },
    "keys": { "ctrlKey": false, "shiftKey": false, "altKey": false, "metaKey": false },
    "elements": {
      "target": { "id": "hero", "type": "DIV", "domType": "HTMLDivElement", "identifier": "div#hero" }
    }
  }
}

`selection`

Fires when the user finishes a text selection.

{
  "type": "selection",
  "data": {
    "text": "the selected text string",
    "elements": {
      "anchorNode": { "type": "#text", "data": "full text of node", "offset": 4 },
      "focusNode":  { "type": "#text", "data": "full text of node", "offset": 22 }
    }
  }
}

`timeInPage`

Fires on a repeating interval (default 2.5 s). Pauses automatically when the tab is hidden (Page Visibility API).

{
  "type": "timeInPage",
  "data": { "timePassed": 7500 }
}

`performance`

One-shot at page load. Uses PerformanceNavigationTiming (via PerformanceObserver).

{
  "type": "performance",
  "data": {
    "timing": {
      "domContentLoadedEventEnd": 312.4,
      "loadEventEnd": 541.8,
      "responseStart": 84.2,
      "responseEnd": 190.1,
      "domInteractive": 295.0
    }
  }
}

`webVitals`

Fires for each Core Web Vital as it becomes available: CLS, FCP, INP, LCP, TTFB.

{
  "type": "webVitals",
  "data": {
    "name": "LCP",
    "value": 1842.5,
    "rating": "good",
    "delta": 1842.5,
    "id": "v3-1720000000000-1234"
  }
}

`environment`

One-shot at init. Rich device and session context.

{
  "type": "environment",
  "data": {
    "darkMode": true,
    "reducedMotion": false,
    "colorGamut": "p3",
    "cpuCores": 10,
    "deviceMemory": 8,
    "devicePixelRatio": 2,
    "screenWidth": 2560,
    "screenHeight": 1440,
    "viewportWidth": 1440,
    "viewportHeight": 900,
    "pointerType": "mouse",
    "hasHover": true,
    "maxTouchPoints": 0,
    "language": "en-US",
    "languages": ["en-US", "it-IT"],
    "timezone": "Europe/Rome",
    "hourCycle": "h23",
    "referrer": "https://google.com",
    "historyLength": 3,
    "isIframe": false,
    "isStandalone": false,
    "serviceWorker": true,
    "webAssembly": true
  }
}

`network`

Fires at init and again on connection change. Requires navigator.connection (Chrome/Edge).

{
  "type": "network",
  "data": { "effectiveType": "4g", "downlink": 10, "rtt": 50, "saveData": false }
}

`longTask`

Fires for every main-thread task exceeding 50 ms. Requires longtask PerformanceObserver support (Chrome/Edge).

{
  "type": "longTask",
  "data": { "duration": 87.3, "startTime": 1234.5 }
}

`slowResource`

Fires when a network resource takes more than 1 000 ms to load.

{
  "type": "slowResource",
  "data": {
    "name": "https://example.com/large-image.jpg",
    "duration": 1842,
    "initiatorType": "img",
    "startTime": 400.2
  }
}

`browserAI`

One-shot detection of browser AI APIs (Chrome 127+). Never invokes the model.

{
  "type": "browserAI",
  "data": { "hasChromeAI": true, "chromeAIModel": "readily", "hasWebNN": false }
}

`privacySignals`

Fires first, before any other listener is set up. If gpc === true (Global Privacy Control), Cerbero calls destroy() and emits no further events.

{
  "type": "privacySignals",
  "data": { "gpc": false, "doNotTrack": false, "gpcAutoDisabled": false }
}

`orientationChange`

Fires when the screen orientation changes (mobile/tablet).

{
  "type": "orientationChange",
  "data": { "orientationType": "landscape-primary", "angle": 90 }
}

`elementVisible`

Fires when an observed element enters the viewport (≥50% visible). Requires a call to observeElements().

{
  "type": "elementVisible",
  "data": { "selector": ".hero-cta", "visibleRatio": 0.82,
            "element": { "identifier": "div.hero-cta", "type": "DIV" } }
}

`navigation`

Fires on SPA route changes. Uses Navigation API when available; falls back to popstate + hashchange.

{
  "type": "navigation",
  "data": { "from": "https://example.com/home", "to": "https://example.com/about",
            "navigationType": "push" }
}

`pageUnload`

Fires on pagehide. Gives you the total time-on-page before the user leaves.

{
  "type": "pageUnload",
  "data": { "timeOnPage": 42300 }
}

Note: to send a beacon to your own server on unload, call navigator.sendBeacon() from your addEventListener callback when you receive this event.

`keyboardShortcut`

Fires only when a modifier key (Ctrl / Meta / Alt) is held. Never records bare keystrokes.

{
  "type": "keyboardShortcut",
  "data": {
    "key": "s",
    "combo": "ctrl+s",
    "ctrlKey": true, "metaKey": false, "altKey": false, "shiftKey": false
  }
}

Plugin System

Plugins push custom events through the same worker pipeline as built-in events.

import type { CerberoPlugin, PluginEmitter } from 'cerbero';

const myPlugin = (): CerberoPlugin => ({
  name: 'myPlugin',
  init(emit: PluginEmitter) {
    // emit any event type
    emit('myEvent', { foo: 'bar' });

    // optionally return a cleanup function called on destroy()
    const timer = setInterval(() => emit('myEvent', { tick: Date.now() }), 5000);
    return () => clearInterval(timer);
  },
});

cerbero.use(myPlugin());

Built-in opt-in plugins

The library ships four ready-made grey-area plugins (opt-in — you decide whether to use them):

Plugin	Import	Emits	Description
Fingerprint	`src/plugins/fingerprint`	`fingerprint`	Canvas, WebGL, and AudioContext hashes
Extended Env	`src/plugins/extended-env`	`extendedEnv`	Speech voices, media device counts, storage, permissions, keyboard layout
Behavioral	`src/plugins/behavioral`	`behavioralMouse`, `behavioralKeyboard`	Mouse velocity/acceleration + keystroke timing (no key values)
WebRTC IP	`src/plugins/webrtc`	`webrtcIp`	Local and public IPs via RTCPeerConnection ICE candidates

import { fingerprintPlugin } from './src/plugins/fingerprint';
import { extendedEnvPlugin } from './src/plugins/extended-env';
import { behavioralPlugin }  from './src/plugins/behavioral';
import { webrtcPlugin }      from './src/plugins/webrtc';

cerbero
  .use(fingerprintPlugin())
  .use(extendedEnvPlugin())
  .use(behavioralPlugin({ mouseDynamics: true, keystrokeDynamics: true, emitInterval: 5000 }))
  .use(webrtcPlugin());

Selective Tracking

Pass an events array to only activate the trackers you need:

const cerbero = new Cerbero({
  events: ['click', 'scroll', 'webVitals', 'environment'],
});

privacySignals always runs regardless of this list — it is a legal requirement for GPC support.

Batching

Collect multiple events before flushing to your callback. Useful for sendBeacon or rate-limited endpoints.

// Flush every 10 events
const cerbero = new Cerbero({ batchSize: 10 });

// Flush every 2 seconds
const cerbero = new Cerbero({ batchInterval: 2000 });

cerbero.addEventListener((events) => {
  // events is unknown[] when batching is enabled
  navigator.sendBeacon('/analytics', JSON.stringify(events));
});

Breaking Changes from v1.x

Change	v1.x	v2.x
No singleton export	`import cerbero from 'cerbero'`	`import { Cerbero } from 'cerbero'; const c = new Cerbero()`
`addEventListner` typo	`cerbero.addEventListner(cb)`	`cerbero.addEventListener(cb)` (deprecated alias kept)
`mouseExit` payload key	`data.elements.fromElement`	`data.elements.target`
`performance` timestamps	Absolute epoch ms (`navigationStart: 1611...`)	Relative ms from navigation start (`domContentLoadedEventEnd: 312.4`)
Web Vitals	FID	INP (Interaction to Next Paint, replacing FID in web-vitals v3+)
`scroll` payload	Included full `elements.target` DOM node	Only `data.scroll` — no elements

Contributing

See CONTRIBUTING.md.

Contributors

Thecreazy

Core

TheBous

Core

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 195 Commits
.github		.github
.husky		.husky
docs		docs
src		src
.babelrc		.babelrc
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LICENSE.MD		LICENSE.MD
README.MD		README.MD
jest.setup.js		jest.setup.js
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

🐾 Cerbero

Table of Contents

Install

Quick Start

Constructor Options

Public API

addEventListener(callback)

setTimeInPageInterval(ms)

observeElements(selector)

use(plugin)

destroy()

Event Reference

click

rageClick

scroll

mouseExit

selection

timeInPage

performance

webVitals

environment

network

longTask

slowResource

browserAI

privacySignals

orientationChange

elementVisible

navigation

pageUnload

keyboardShortcut

Plugin System

Built-in opt-in plugins

Selective Tracking

Batching

Breaking Changes from v1.x

Contributing

Contributors

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`addEventListener(callback)`

`setTimeInPageInterval(ms)`

`observeElements(selector)`

`use(plugin)`

`destroy()`

`click`

`rageClick`

`scroll`

`mouseExit`

`selection`

`timeInPage`

`performance`

`webVitals`

`environment`

`network`

`longTask`

`slowResource`

`browserAI`

`privacySignals`

`orientationChange`

`elementVisible`

`navigation`

`pageUnload`

`keyboardShortcut`