A first-party path
Serve the tracker and its collect address from your own domain, and still count each visitor at their own address.
Filter lists block third-party analytics hosts. A path on your own domain,
such as /_pa, is not on them, and a page that sends no referrer still has
an origin the collector can check. It costs one thing: your proxy is now the
peer the collector sees, so without the step below every visitor would be
stored at your proxy's address.
On Next.js, @chokh/next does all of this. Anywhere else, two
pieces.
The tracker file
a.js (and v.js, e.js) are plain files: a rewrite or a plain proxy of
/_pa/a.js to https://analytics.example.com/a.js is right for them. Point
the tag at your path, and say where to post:
<script defer data-site="my_site" data-api="/_pa" src="/_pa/a.js"></script>
The collect address
POST /_pa/collect has to carry the visitor's address across, signed, or
anybody could claim any address. In Node, with @chokh/sdk-node:
import { signForwardedAddress } from '@chokh/sdk-node';
const CHOKH_URL = process.env.CHOKH_URL ?? ''; // https://analytics.example.com
const SECRET = process.env.CHOKH_PROXY_SECRET ?? ''; // the same as the server's
// Your handler for POST /_pa/collect. `address` is the visitor's address as
// your own edge reports it, never a header the visitor could send.
export async function forwardCollect(request: Request, address: string): Promise<Response> {
const ts = Date.now();
const headers = new Headers({
'content-type': request.headers.get('content-type') ?? 'text/plain',
'user-agent': request.headers.get('user-agent') ?? '',
'x-chokh-forwarded-for': address,
'x-chokh-forwarded-sig': `${ts}.${signForwardedAddress(SECRET, address, ts)}`,
});
// The browser's own Origin and Client Hints, read by the collector as they
// would be without a proxy.
for (const [name, value] of request.headers) {
if (name === 'origin' || name.startsWith('sec-ch-ua')) {
headers.set(name, value);
}
}
return fetch(`${CHOKH_URL}/api/collect`, { method: 'POST', headers, body: await request.text() });
}
Then tell your Chokh to believe it:
REAL_IP_HEADER=X-Chokh-Forwarded-For
CHOKH_PROXY_SECRET=<the same 32 or more characters as your proxy>
Four things to know:
- A bad signature is never a refusal. A missing, forged or stale one falls back to the address the collector sees, and the batch is still counted. A mistake in your proxy costs addresses, not traffic.
- The secret is for servers only. A browser that could read it could claim any address.
- Forward the browser's own headers: the user agent, the Client Hints and the origin, as in the example. A proxy that sends its own user agent turns every visitor into that.
- The signature lasts two minutes, either side of the moment it was made, so a header copied out of a log is worth nothing soon after.
In another language, the signature is
base64url(hmac_sha256(CHOKH_PROXY_SECRET, address + "\n" + ts)), with ts
the time in milliseconds, sent as X-Chokh-Forwarded-Sig: <ts>.<signature>.