First-party proxy
Serve the tracker from your own host so Safari keeps remembering Pro visitors and ad blockers do not block it: recipes and the Check proxy step.
Why a proxy
A first-party proxy serves the tracker and its endpoints from your own host, under a path such as https://site.com/oa/, and forwards them to our collector. It is optional and matters only on a Pro site. Without one, Pro still works. With one, two things get better:
- Safari keeps remembering visitors. Safari deletes storage a script wrote after seven days without a click, tap or key press on your site, and shortens cookies set from another address. A cookie set by a path on your own host survives both.
- Ad blockers that block our collector's host no longer block your analytics.
A subdomain pointed at us with a CNAME (stats.site.com) does not work and is refused: Safari treats it as a third party.
What the proxy does and does not forward
- It forwards the script, events, the realtime heartbeat, the visitor-id request, the tracker config and the proxy check.
- It sends your site's proxy key and the visitor's address, taken from a source the visitor cannot forge (Vercel's x-real-ip, Cloudflare's CF-Connecting-IP, nginx's $remote_addr).
- It forwards only our own anchor cookies, never your users' session, cart or consent cookies, and never an Authorization header.
- It caches the script and nothing else. Responses that set a cookie are never cached.
- A proxy key reads nothing. A leaked key lets someone fake visitor addresses for that one site, and nothing more.
Setup
Create a proxy key
In Settings → Proxy, create a key. It is shown once. Store it as a server-side secret: an environment variable without a public prefix (never NEXT_PUBLIC_), a Worker secret, or a root-only nginx include.
To share the visitor-id cookie across your subdomains, the site's domain list must contain the bare registrable domain (for example example.com): a list holding only www.example.com gets a cookie for that one host.
Install the recipe for your platform
Next.js
One route handler, app/oa/[...path]/route.ts.
Cloudflare Worker
A Worker on your zone, routed at /oa/*.
nginx
Two location blocks and a key include.
Every file is self-contained; paste it as it is. All recipes and their notes are in the examples/proxy folder of the repository.
Run Check proxy
Required. In Settings → Proxy, type your proxy's address and press Check proxy. Your browser calls <address>/v1/proxy/check through the proxy, and the collector reports whether the request came through a proxy and whether its key is valid for this site. Do not move on until both are true.
Point the snippet at your host
<script
async
src="https://site.com/oa/oa.js"
data-key="YOUR_TRACKING_KEY"
data-collector="https://site.com/oa"
></script>When the key is wrong or missing
Nothing breaks: events are still accepted, and the collector ignores the forwarded address. But every visitor then seems to come from your proxy's few addresses, so per-address limits drop events and locations read as your proxy's. The dashboard shows a banner when your last check found this. Fix it quickly; it is lost data, not just blurred data.
Rotating and revoking the key
Rotating creates a new key, shown once, and the previous key keeps working for 24 hours so you can deploy the new one without a gap. If the old key has leaked, choose Rotate and revoke the old key now: it stops working at once.
HttpOnly, Secure and SameSite=Lax, scoped to your registrable domain, and refreshed on every proxied response.