# Install the tracking script
> Add the PilotFox script tag to your site, choose what it records, track single-page apps, allow it in a Content Security Policy and verify the installation.
## The script tag
Put this tag in the `` of every page, with your site's id in place of `SITE_ID`. The site's settings show the tag with the id filled in (Site settings → Tracking code).
```html
```
- `defer` lets the browser download the script early and run it once the page has been parsed.
- Keep it a classic ``.
Each example forwards `/_pf/*` to `https://pilotfox.app/api/*`, sets `X-PilotFox-IP` from the connection your server received (never from a header your visitors can send), adds the secret, and drops your visitors' cookies: they belong to your site, and PilotFox reads none.
### Next.js
```ts
// proxy.ts at the root of your app (Next.js 16).
// On Next.js 15 or older: name the file middleware.ts and the function middleware.
import { NextResponse, type NextRequest } from "next/server";
export function proxy(request: NextRequest) {
const { pathname, search } = request.nextUrl;
const url = new URL(pathname.replace(/^\/_pf/, "/api") + search, "https://pilotfox.app");
const headers = new Headers(request.headers);
headers.delete("cookie"); // your visitors' cookies stay on your site
headers.set("x-pilotfox-proxy-secret", process.env.PILOTFOX_PROXY_SECRET ?? "");
// The visitor's address: x-forwarded-for on Vercel, which sets it. Self-hosted: the
// header your own front proxy sets, never one your visitors can send.
headers.set("x-pilotfox-ip", request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "");
return NextResponse.rewrite(url, { request: { headers } });
}
export const config = { matcher: "/_pf/:path*" };
```
Vercel sets `x-forwarded-for` to the visitor's address and overwrites any value the visitor sends. Behind your own load balancer, use the header it sets. Plain `rewrites` in `next.config.js` can forward the path but cannot add headers, so every visitor would have your server's address.
### Caddy
```
# Inside your site's block in the Caddyfile.
# PILOTFOX_PROXY_SECRET is read from Caddy's environment.
handle_path /_pf/* {
rewrite * /api{path}
reverse_proxy https://pilotfox.app {
header_up Host {upstream_hostport}
header_up X-PilotFox-IP {client_ip}
header_up X-PilotFox-Proxy-Secret {$PILOTFOX_PROXY_SECRET}
header_up -Cookie
}
}
```
`{client_ip}` is the address of the connection, or the one your trusted proxies report if you set `trusted_proxies`.
### nginx
```nginx
# Inside your site's server block. Paste the secret where it says so
# (nginx reads no environment variables here). Behind a load balancer,
# set $remote_addr from it with the realip module first.
location /_pf/ {
proxy_pass https://pilotfox.app/api/;
proxy_ssl_server_name on; # send the name pilotfox.app for TLS (off by default)
proxy_set_header Host pilotfox.app;
proxy_set_header X-PilotFox-IP $remote_addr;
proxy_set_header X-PilotFox-Proxy-Secret "PASTE_THE_SECRET_HERE";
proxy_set_header Cookie ""; # your visitors' cookies stay on your site
}
```
### Cloudflare Worker
```js
// A Worker on the route example.com/_pf/* of your zone. Add the secret with
// `wrangler secret put PILOTFOX_PROXY_SECRET` (or the dashboard's Variables and Secrets).
export default {
async fetch(request, env) {
const { pathname, search } = new URL(request.url);
const url = new URL(pathname.replace(/^\/_pf/, "/api") + search, "https://pilotfox.app");
const headers = new Headers(request.headers);
headers.delete("cookie"); // your visitors' cookies stay on your site
headers.set("x-pilotfox-ip", request.headers.get("cf-connecting-ip") ?? "");
headers.set("x-pilotfox-proxy-secret", env.PILOTFOX_PROXY_SECRET);
return fetch(url, { method: request.method, headers, body: request.body });
},
};
```
### Notes
- A request whose secret is wrong, was replaced or removed, or whose `X-PilotFox-IP` is missing or not a single IP address is refused with `400 Invalid proxy secret`; a secret of another site with `400 The proxy secret is for another site`. Nothing from it is recorded.
- *Replace* in the settings stops the old secret at once: update your server right after. *Remove* turns the proxy off: requests that still carry the secret are refused.
- If the secret leaks, replace it. It lets its holder choose the IP address of events for that one site, nothing else: it gives no access to your data.
- Visitors are located from their own address. Cloudflare's location headers are not used for requests that come through a proxy.
- Your Content Security Policy then needs only your own origin (`'self'`) for the script and its requests.
## Verify the installation
*Verify installation* (in Site settings → Tracking code, and at the end of adding a site) loads your site's home page, over HTTPS and then HTTP if HTTPS does not answer, and looks for the PilotFox tag with your site's id. It reports one of: installed, not installed, a tag with another site's id, or that the page could not be loaded.
Then open the site's dashboard and visit your site in another tab: the live view shows the visit.
## Keep traffic out
In Site settings:
- **Allowed hostnames** (Privacy & identity): events from any other hostname are dropped, for example from a staging copy that still carries the tag. `*.example.com` matches every subdomain, at any depth (`www.example.com`, `a.b.example.com`), but not `example.com` itself: list that separately.
- **Exclusions:** drop traffic by IP address or range, country, path, user agent or network (ASN), for example your office or uptime monitors.
- **Bots:** bot traffic is dropped by default and shown in the Bots report instead.
- **Your own browser:** open any page of your site with `?pilotfox_ignore=true` added to the address (for example `https://example.com/?pilotfox_ignore=true`), or run `pilotfox.optOut()` in the browser console there. That browser is no longer counted on your site; `?pilotfox_ignore=false` undoes `?pilotfox_ignore=true` (never `optOut()`, which may be a visitor's own choice), and `pilotfox.optIn()` undoes either. It is remembered in the browser's `localStorage`, so clearing site data undoes it too.
- **Tagged links:** Site settings → Link builder adds campaign (`utm_*`) or affiliate (`?ref=`) parameters to a link of your site, so visits from posts on X, LinkedIn, Medium or a newsletter, which often arrive without a referrer, are reported under their campaign.