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.

Because every subdomain is accepted, a staging, development or test environment that runs the snippet sends its traffic into your production data. To keep it out, add those hosts under Settings → Domains → Excluded hostnames (workspace admins only):

• staging.example.com excludes exactly that host.
• *.k8s.example.com excludes every host under k8s.example.com, such as per-branch test deployments (pr-123.k8s.example.com), but not k8s.example.com itself.

Traffic from an excluded host is ignored everywhere: events aren’t stored, visitors aren’t recovered or fingerprinted, and identify() and form submissions from it are refused. Patterns must be under one of your verified domains, and changes apply within about 30 seconds. Data stored before you added a rule isn’t removed.

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

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

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

If your site sends a Content-Security-Policy, allow https://events.pathbound.ai in script-src and connect-src, and https://api.pathbound.ai in connect-src (identify() calls it).

Installed before October 2026 with tracker.pathbound.ai/tracker.js? Nothing to change: that address keeps working, and its events keep going to tracker.pathbound.ai.

The script:

• Runs on DOMContentLoaded (or immediately, if the DOM is already ready).
• Reads/sets the pathbound_visitor_id and pathbound_session_id cookies. In a mobile app’s webview, where cookies aren’t kept, it keeps the visitor ID and the external ID in local storage as well (see App webviews).
• 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 events.pathbound.ai/track.
• If a batch isn’t delivered (the events server doesn’t answer, or answers that it can’t take it now), keeps its events in the page’s memory and sends them again, waiting longer between tries, until the server takes them. Each event carries an ID of its own, so a batch that arrives twice is stored once. Events still waiting when the page is closed are lost.

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 one console.warn for each kind of failure, such as a batch not delivered yet.
• 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 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';