Install the script
Updated 2026-11-02
The snippet
Copy your snippet from Project in the dashboard, under Install. Put it in the <head> shared by every page.
<script defer src="https://headstream-ingest.super-dream-7005.workers.dev/t.js" data-key="YOUR_KEY"></script>
Don't add it to a single page, and don't add it twice. Your key is public by design, and it starts with hs_.
What it records
| Data | When |
|---|---|
| Pageview | On load, and on each route change in a single-page app |
| Clicks | On each click |
| Scroll depth | When the visitor leaves the page |
| Form fields | On submit: email, name, company, phone and heard_about |
form_submit event | On each form submit |
Password and card fields are skipped, along with hidden fields and any field whose name contains words such as secret, token or ssn.
The script sets a first-party cookie named hs_vid, which lasts up to 400 days, and keeps a copy in local storage. It writes the cookie on your apex domain so that a visitor keeps the same ID across subdomains.
Domains
Events are accepted only from domains on your project. Subdomains are included. Add more under Project, in the Domains card. localhost can't be added, so test on a deployed site.
To carry a visitor across two different domains, add ?_hsid=VISITOR_ID to the link. The value is the 32-character hs_vid ID.
First-party tracking
Routing the script through your own domain means ad blockers miss less and the visitor cookie can last longer, because the server sets it. Add a rewrite, then swap in the snippet. Copy both from the First-party tracking card.
Next.js:
async rewrites() {
return [{ source: "/_hs/:path*", destination: "https://headstream-ingest.super-dream-7005.workers.dev/:path*" }];
}
Vercel:
{ "rewrites": [{ "source": "/_hs/:path*", "destination": "https://headstream-ingest.super-dream-7005.workers.dev/:path*" }] }
Snippet:
<script defer src="/_hs/t.js" data-key="YOUR_KEY"></script>
Locked version
The Install card can also show a pinned snippet with an integrity hash. The browser refuses the file if it ever changes. You'll update it by hand to get tracker improvements.
Turn off clicks and scroll
Add data-heatmaps="off" to the tag.
Session recordings
Recordings are optional and use a second script, which you'll find under Session recordings. Form fields are always masked. Add the class hs-mask to hide text, or hs-block to hide an element. Recordings are kept for 90 days.
Exclude your team
Under Project, list paths and IP addresses to leave out. A path ending in * matches everything under it. Matching events are flagged and left out of reports, so removing a rule brings future traffic back.
Content Security Policy
If you set a CSP, allow the ingest host in script-src and connect-src.