Tracker — Custom events

The tracker exposes a global pathbound.track(name, data) you can call from anywhere on the page. Custom events are written to the same events collection as the auto-tracked ones and land in GET /v1/events immediately.

API

window.pathbound.track(eventName: string, data?: Record<string, unknown>): void;

• eventName — any string that fits your taxonomy (e.g. pricing_calculator_used, demo_requested, feature_flag_clicked). Names with snake_case are conventional but not required.
• data — any JSON-serializable object. Avoid PII unless the visitor has identified.

The call is synchronous and non-blocking: events are queued and batched. If the page unloads before the batch fires, the tracker uses navigator.sendBeacon to flush.

Examples

A pricing-calculator interaction

calculator.on('change', (state) => {
  pathbound?.track('pricing_calculator_used', {
    selectedPlan: state.plan,
    seats: state.seats,
    addons: state.addons,
    estimatedTotal: state.totalUsd,
  });
});

A demo-request CTA click that you treat differently from the auto-tracked button_click

document.querySelector('#book-demo').addEventListener('click', (e) => {
  pathbound?.track('demo_requested', {
    source: 'header',
    referrer: document.referrer,
  });
});

SPA route change

router.afterEach((to) => {
  pathbound?.track('page_view', {
    title: document.title,
    path: to.path,
  });
});

Optional-chaining safety

The tracker may not be loaded yet (or may be blocked by a content blocker, or DNT’d). Always call with pathbound?.track(...) — never pathbound.track(...) — so a missing tracker is a no-op rather than a ReferenceError.

Naming conventions

Aim for verb-object names that describe what the user did, not what your code did:

• ✅ demo_requested, pricing_calculator_used, tutorial_completed
• ❌ submitDemoForm, pricing_handler, step_3

Use get_event_types to inspect the names you’ve recorded. The dashboard segment builder reads from this set, so the names you pick become the building blocks for downstream targeting.

What lands in the event

Custom events get the same automatic envelope as auto-tracked ones — visitor_id, session_id, url, domain, userAgent, referrer, external_contact_id, ga_user_id — plus your data payload. From the consumer side (/v1/events), there’s no distinction between an auto-tracked page_view and a custom pricing_calculator_used.

Volume and rate limits

The tracker is rate-limited per domain and per IP. For high-frequency interactions (mouse moves, keystrokes, scroll positions), don’t fire one event per interaction — sample or aggregate client-side first.