Tracker — Tracked events

The tracker fires events automatically with no configuration. Each event is wrapped in a standard envelope on the wire and lands in your tenant’s events collection ready for GET /v1/events.

Event envelope

Every event arrives at the backend with this shape (the tracker batches up to 10 events per request):

{
  "event": "page_view",
  "data": { /* event-specific payload */ },
  "timestamp": "2026-04-29T11:23:45.000Z",
  "url": "https://example.com/pricing",
  "domain": "example.com",
  "visitorId": "vis_abc",
  "sessionId": "sess_xyz",
  "external_contact_id": null,
  "ga_user_id": "GA1.1.1234.5678",
  "userAgent": "Mozilla/5.0 …",
  "referrer": "https://google.com/",
  "screenResolution": "1920x1080"
}

The fields below describe the data payload for each event.

Page lifecycle

page_view

Fires on script load and on every manual pathbound.track('page_view', …) call (you’ll do this for SPA route changes).

{
  "title": "Pricing — Example",
  "path": "/pricing",
  "utmParams": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring-2026"
  },
  "userAgent": "…",
  "referrer": "…",
  "screenResolution": "1920x1080",
  "pageLoadTime": 412
}

first_visit

Fires once per browser, the first time the tracker assigns a fresh pathbound_visitor_id (i.e. no recoverable visitor existed for the device fingerprint).

{
  "landingPage": "https://example.com/pricing",
  "landingPath": "/pricing",
  "initialReferrer": "https://google.com/",
  "utmParams": { /* same as page_view */ },
  "title": "Pricing — Example",
  "userAgent": "…",
  "screenResolution": "1920x1080",
  "pageLoadTime": 410
}

User interactions

button_click

Fires on every native <button> click anywhere in the document.

{
  "text": "Get a demo",
  "class": "btn btn-primary",
  "id": "demo-cta",
  "elementType": "button"
}

link_click

Fires on every <a> click. isExternal is true if the link’s hostname differs from the current page’s hostname.

{
  "text": "Read the docs",
  "href": "https://docs.pathbound.ai/getting-started/introduction/",
  "class": "footer-link",
  "id": "",
  "elementType": "link",
  "isExternal": true
}

form_submit

Fires on every native <form> submit. Form field values are not captured here — submit them to the public form-submission endpoint for that.

{
  "formId": "demo-form",
  "formClass": "contact-form",
  "action": "/submit",
  "method": "post"
}

Wistia video

Auto-detected when a <wistia-player> element is on the page (or added later via DOM mutation).

video_play

Fires when playback begins or resumes.

{
  "provider": "wistia",
  "mediaId": "abc123def",
  "videoName": "Product overview",
  "duration": 187,
  "currentTime": 0,
  "pageTitle": "Home — Example",
  "pagePath": "/",
  "wistiaVisitorKey": "v1-…"
}

video_pause

Fires on pause, including when the user navigates away.

{
  "provider": "wistia",
  "mediaId": "abc123def",
  "videoName": "Product overview",
  "duration": 187,
  "currentTime": 64,
  "secondsWatched": 58,
  "pageTitle": "Home — Example",
  "pagePath": "/"
}

video_complete

Fires when the video reaches its natural end.

{
  "provider": "wistia",
  "mediaId": "abc123def",
  "videoName": "Product overview",
  "duration": 187,
  "secondsWatched": 187,
  "pageTitle": "Home — Example",
  "pagePath": "/"
}

video_milestone

Fires once each at 25%, 50%, 75%, and 100% of duration. The 100% milestone may fire alongside video_complete.

{
  "provider": "wistia",
  "mediaId": "abc123def",
  "videoName": "Product overview",
  "milestone": 50,
  "currentTime": 94,
  "duration": 187,
  "pageTitle": "Home — Example",
  "pagePath": "/"
}

video_conversion

Fires when a Wistia Turnstile (in-video email capture) is submitted.

{
  "provider": "wistia",
  "mediaId": "abc123def",
  "videoName": "Product overview",
  "duration": 187,
  "currentTime": 32,
  "pageTitle": "Home — Example",
  "pagePath": "/",
  "conversionType": "email_only",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

The submitted email is the most reliable identifier the tracker captures from in-page interactions. If the visitor isn’t already linked to a contact, video_conversion is what flips them from anonymous to identified.

System events

_fingerprint_update

Internal — fired when the tracker computes a fresh device fingerprint. Used by the server to maintain the fingerprint → visitor ID mapping. Most consumers can ignore this event type when reading /v1/events.

Custom events

Anything your site fires via pathbound.track(name, data) lands in /v1/events with the same envelope.