Tracker — Install

In the Pathbound dashboard, go to Settings → Domains and add the hostname your site runs on (e.g. example.com). Verification confirms the tenant owns the domain so the tracker server will accept events from it.

The tracker rejects events from domains that aren’t verified — this is what protects your tenant from someone else dropping your snippet on their site.

Place this just before the closing </body> tag on every page you want to track:

<script async src="https://tracker.pathbound.ai/tracker.js"></script>

That’s it. No configuration, no API keys, no callbacks to wait for.

The script:

• Runs on DOMContentLoaded (or immediately, if the DOM is already ready).
• Reads/sets the pathbound_visitor_id and pathbound_session_id cookies.
• Fires page_view on load and on every client-side route change, plus page_leave when a page is navigated away from. Attaches click and submit listeners for the rest of the session.
• Batches events (up to 10 per batch or 2 seconds) and POSTs to tracker.pathbound.ai/track.

Open your site, click around, then in another tab make this REST call:

curl "https://api.pathbound.ai/v1/events?limit=5&sort_dir=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

You should see page_view, button_click, etc. with the correct domain and url.

If nothing appears within a few seconds:

• Check the browser console — the snippet logs to console.warn on batch failures.
• Confirm the domain is verified in the dashboard. The tracker silently drops events from unverified domains, so missing events are almost always either a missing or mistyped domain entry under Settings → Domains, or a request whose Origin doesn’t match the verified root domain (e.g. running on a preview subdomain that hasn’t been added).
• Confirm the user has not set pathbound_dnt=1 (the do-not-track opt-out cookie).

Single-page app navigations are captured automatically. The tracker patches history.pushState/replaceState and listens for popstate/hashchange, so each client-side route change fires its own page_view (with navigationType: "spa" and the previousPath the visitor came from) and a page_leave for the page being left (with timeOnPage). A route counts as a new view when pathname + search + hash changes; repeating the same URL is ignored. No configuration is required — history-mode and hash-mode routers both work.

If you’d rather host the tracker on your own subdomain (e.g. tracker.yourcompany.com), run the @pathbound/tracker service on your infrastructure and set TRACKER_PUBLIC_HOST=tracker.yourcompany.com. The snippet URL just becomes https://tracker.yourcompany.com/tracker.js. Events still write to the shared backend MongoDB, so they show up in your tenant exactly the same way.

This is useful for cookie-domain alignment (first-party context for pathbound_visitor_id) or when corporate networks block pathbound.ai.

If you load the snippet via Google Tag Manager or similar, don’t place it inside an iframe — the cookie scope and Referer validation depend on running in the page’s main document context.

Set the pathbound_dnt cookie to 1 on your domain. The tracker checks this cookie at the very top of the script and exits immediately if it’s present. This is the recommended way to honor a user-level “do not track” preference.

document.cookie = 'pathbound_dnt=1; path=/; max-age=31536000; SameSite=Strict; Secure';