First-party Tag Gateway

What the gateway changes#

By default the tracker file loads from the AdPix CDN host and the beacon goes to the AdPix collector host. Both are hosts outside your site: ad-blocker lists know them, and the cookie the collector wanted to write is a third-party cookie.

With the Tag Gateway, a subdomain of your own domain — metrics.<your domain> by default — sits in front of all that traffic and proxies it to AdPix.

Identity works in both modes; in direct mode it rides the durable ID the tracker keeps in local storage. What the gateway adds is longer persistence and a much smaller blocked surface.

What you need#

• Access to the domain's DNS, for one CNAME record.
• A reverse proxy holding a TLS certificate for that subdomain. The console generates ready configs for Caddy, nginx and a Cloudflare Worker.
• Editor level or above on the property — generating a bundle mints a credential, so it is protected like any property-settings change. Viewing an existing bundle only needs report-read access.

Generate the bundle#

Each data stream's bundle is stored on the stream itself — the token is kept encrypted and the bundle is re-rendered every time you open the section. So you do not have to keep a copy anywhere, and you never have to regenerate just to read it again. The standalone wizard under Settings behaves the older way: it shows the token once.

The paths that must be proxied#

This is the most important part of the page. The generated config carries a strict allowlist, and anything outside it gets a 404. The list is the entire tracker surface, not just the tracker file and the beacon:

The Caddy, nginx and Cloudflare Worker versions are rendered from one source, so all three carry exactly this list. If you run a different proxy, port the whole list to it.

The headers the proxy adds#

The generated config sets four headers on every request:

Take the last two seriously: without them the collector sees your proxy server's IP, and country, city and network collapse to one value for every visitor. The Caddy and nginx configs set all four; the Cloudflare Worker sets only the two X-Site-* headers, because Cloudflare already forwards the visitor's address itself.

Any request carrying X-Site-Key must also carry a valid X-Site-Token, or the answer is a 403. Direct-mode requests, which do not carry that header, are unaffected.

Rotating the token with no downtime#

The proxy token is a credential and sooner or later has to change — after someone leaves, after a config leak, or simply as periodic hygiene. Only an argon2id hash of it is stored.

The detail that makes rotation painless: the collector accepts any non-revoked token for that property. Several tokens can be valid at once.

Listing and revoking happen through the API:

curl 'https://api.adpix.io/api/v1/proxy-tokens?site=<property_id>' \
  -H 'Cookie: ap_admin=…'

{
  "site_id": "…",
  "tokens": [
    { "prefix": "9f2a1c40", "created_at": "…", "revoked_at": "",  "active": true  },
    { "prefix": "3b7e0d55", "created_at": "…", "revoked_at": "…", "active": false }
  ]
}

curl -X DELETE 'https://api.adpix.io/api/v1/proxy-tokens?site=<property_id>&prefix=3b7e0d55' \
  -H 'Cookie: ap_admin=…'

The list shows only each token's eight-character prefix, never the value itself; that prefix is what revoking takes. Listing needs report-read access; revoking needs the property-settings edit capability.

Diagnosing it#

The same Tag-Gateway section runs a diagnostic. Four checks run in order, each with its own remediation:

The first three are diagnostic — they explain why data is not arriving. The fourth is definitive: the stream is not marked verified until a real event lands.

The stream's own status shows the same thing and has five states: awaiting install, proxy live, tag found in the page source, receiving data, and error. Only "receiving data" means you are done.

You can also call the health URL yourself; it is printed in the bundle, and a 200 means the proxy is alive and reaching AdPix.

After it is live#

• Swap the snippet. While your page still loads the direct tag, the gateway is up but no traffic goes through it.
• Keep one install path. Do not load the tag from both your site template and a tag manager.
• Re-run the diagnostic after every proxy change. A Caddy or nginx upgrade sometimes loses the path list, and the first symptom is an empty consent banner or an empty heatmap — not a drop in page views.

The headers and cookies of this path are listed in Cookies and headers, and the exact shape of the send envelope is in The collect envelope.

Frequently asked questions#

Related#