Events — Install

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

Verification is per root domain, and covers every subdomain. Whatever you enter is normalized to the root (app.example.com → example.com; multi-part TLDs like example.co.uk are handled), you verify it once via a DNS TXT record at the root, and traffic from www.example.com, app.example.com, staging.example.com, etc. is all accepted. You decide which subdomains actually send events simply by where you embed the snippet (and per-user via the pathbound_dnt opt-out). Separate root domains (example.com vs example.net) each need their own verification.

The events server rejects events from root 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.

Anonymous tracking is now live. To connect logged-in users to their contact profiles — one window.pathbound.identify() call at login — continue with Identify logged-in users.

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 events server 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 snippet 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 event ingestion 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 snippet 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';