The middleware sees requests your server handles. A marketing site, a docs site or a signup page served from somewhere else is invisible to it, and so are browser agents (an agent driving Chrome) and people on those pages. The browser snippet covers them. Add one line to every page, inside <head>, with the project's public key from the Install page:
<script async src="https://alg.katrinalaszlo.com/t/1.js" integrity="sha384-…" crossorigin="anonymous" data-key="pk_0123456789abcdef0123456789abcdef"></script>Copy the tag from the Install page: it carries the real integrity hash. /t/1.js is version 1, which never changes, so the browser checks the file against the hash (Subresource Integrity) and refuses to run anything else. A fix to version 1 ships as /t/2.js with a new hash; /t/1.js stays as it is, cached for a year. /t.js is the current version, cached for an hour, for tags without integrity.
The public key names the project and is not a secret: it is in every page, so anyone can copy it and send browser events to the project. What those events can and cannot do is below. Never put AGENT_TRAFFIC_KEY in a page.
What it sends, to POST /v1/browser/events on Track and nowhere else:
- A
page_viewevent on load, and again when a single-page app changes the path (history.pushState,replaceState, back and forward).pathis the page's path only: no domain, no query string, no#part, and a token after/invite/,/reset/,/verify/and the other one-time words is replaced with:tokenin the browser, the same rule as "What ingest does to paths". - Your own events:
track("signup_started", { plan: "pro" }). The name follows the event name rules (lowercase letters, digits and_).propsis up to 20 keys of letters, digits and_, each a string of up to 200 characters, a number,true,falseornull, at most 2 KB as JSON per event (4 KB for all the events of one request).path,referrer,webdriver,headless,no_pluginsandno_languagesare set by Track and cannot be props. A call that breaks a rule is not sent and the console says why. To calltrackbefore the script has loaded, define the queue first:<script>window.track = window.track || function () { (window.track.q = window.track.q || []).push(arguments); };</script>. - The referrer's origin only (
https://www.google.com), and only when it is another site. - Four automation signals, each a boolean sent only when true:
webdriver(navigator.webdriveris true, which browsers set when WebDriver, Playwright or Puppeteer drives them),headless(the user agent or its client hints name HeadlessChrome),no_plugins(navigator.pluginsis empty) andno_languages(navigator.languagesis empty). Nothing else about the device is read: no screen size, fonts, canvas or other fingerprinting. - The journey key (below).
Track adds the request's own User-Agent and Accept-Language headers and the time it received the event as occurred_at (a browser clock can be hours off). The client IP is used only to rate-limit: its request counter is named by an HMAC under a key that changes every UTC day, the counter is deleted a day after its last use, and the IP is never stored. Browser events carry no ip_hash and no account_id.
Each event is stored like any other with source browser, and its props, referrer and signals in properties. A session with a browser event whose webdriver or headless flag is true is classified Suspected automation (rule browser_automation_flag, weight 0.8). no_plugins and no_languages are recorded but not used: phones list no plugins either. Browser events count in coverage under sdk_source_breakdown.browser and appear on the Install page under step 5.
What browser events can and cannot affect. Anyone with the public key can send them, with any name, props and User-Agent, so Track trusts them less than your server's events:
- They never reach a funnel or onboarding step, unless you save that step with
from_browser: true(PUT /v1/traffic/funnel, or+browserat the end of its line in Settings). That includes events named like a step (signup,paid) andonboarding_stepevents. - They never count as errors: a
status_codeprop is ignored, and anerrorevent counts only at a step saved withfrom_browser: truethat it names inproperties.step. - They never decide whether a session succeeded or failed, so they never appear under "What agents ran into" on the Friction page or in
fix_next. - Their
User-Agentnever makes a session a Known agent or a Declared agent. A browser event whoseUser-Agentnames one (ChatGPT-Userand the rest of the shipped list) matches no rule at all: its session is Unknown, or Suspected automation when thewebdriverorheadlessflag is set, and the agent is named "Unverified browser". - They never carry an outcome, so they never add revenue, signups or payments, and never change attribution.
- They are not sent to PostHog or GA4 unless you turn that on for the project: Settings, Browser snippet, "Forward browser events too", or
PATCH /v1/projects/:idwith{ "forward_browser_events": true }. It is off for every project until then. Set the site's domain first.
The snippet sends nothing at all, and track does nothing, when the browser sends Do Not Track (navigator.doNotTrack or window.doNotTrack is "1" or "yes", or the older navigator.msDoNotTrack is "1") or Global Privacy Control (navigator.globalPrivacyControl is true). It sets no cookies. It keeps the journey key in sessionStorage for the tab, so the pages of one visit share it; it is gone when the tab closes. That storage may still need a line in your cookie policy or consent banner. Events go with navigator.sendBeacon, else fetch with keepalive, as text/plain so no CORS preflight is needed; the response is not read. Your page's Content-Security-Policy needs https://alg.katrinalaszlo.com in script-src and connect-src.
Which pages may send: when the project has a domain, only pages on that host and its subdomains, over https on the default port, judged by the browser's Origin header; anything else answers 403 origin_not_allowed and is counted on the Install page. Without a domain, any page may send with the key, and the Install page says "Open to any site". Set or clear the domain in Settings, Browser snippet, or with domain on POST /v1/projects or PATCH /v1/projects/:id (null clears it); it is kept as https://<domain>. A name many sites share is refused as a domain, so one project cannot take in every site on a platform: vercel.app, netlify.app, pages.dev, github.io, herokuapp.com, co.uk and the other names in Track's short list of shared hosting and country names. Use your own name under them, such as acme.vercel.app, which also takes preview.acme.vercel.app. The Origin check stops other sites' pages from sending as yours; it cannot stop a script that sends its own Origin header, which is what the limits in section 9 are for.
If someone else is sending with your key, rotate it: Settings, Browser snippet, "Rotate public key", or PATCH /v1/projects/:id with { "rotate_public_key": true }. The old key stops at once (404 from then on), so put the new one in the script tag on every page. The domain, forwarding and rotation changes need the write scope and show in the Agent log.
Refused browser requests are counted per hour, not logged one by one: the Install page (step 5) and install-check show how many were refused in the last 24 hours and why (over the project's daily limit, over one address's daily limit, over the per-second limit, or from a site that is not the project's domain). The snippet does not resend a refused event.
The request body, for reference (the snippet builds it): { "v": 1, "journey": { "id": "j_…", "from": "server" | "snippet" }, "signals": { "webdriver": true }, "referrer": "https://www.google.com" | null, "events": [{ "id": "b_…", "name": "page_view", "path": "/pricing", "props": {} }] }, at most 8 KB and 10 events. Anything malformed is refused whole with 400 naming the field. A good request answers 202 { accepted, rejected } as in section 6.