Set up a first-party analytics proxy

A first-party proxy serves the TinyAnalytics tracking script and forwards its requests through a path on your own domain. Use it when ad blockers prevent requests to dash.tinyanalytics.io, while keeping the same cookieless collection and dashboard. The recommended setup maps one prefix such as /stats to TinyAnalytics and loads the tracking script from that prefix:

https://yourdomain.com/stats/<path> → https://dash.tinyanalytics.io/<path>

Your proxy must strip /stats, preserve the remaining path, method, headers, and body, and pass the visitor’s real IP address. TinyAnalytics uses the IP address and user agent in memory to derive its one-way cookieless visitor ID; it does not write the raw IP address to analytics data.

Prerequisites

A site with the TinyAnalytics tracking script.
Access to your hosting platform’s rewrite or reverse-proxy configuration.
A path prefix on the tracked domain. Use a neutral prefix such as /stats, /ping, or /tel; filter lists can block obvious names such as /analytics.

Configure the proxy

Choose a prefix and forwarding rule

Forward every request under your prefix to the same path at https://dash.tinyanalytics.io, after removing the prefix. Keep the wildcard scoped to that prefix rather than forwarding your whole domain.For example, /stats/script.js must reach /script.js, and /stats/api/track must reach /api/track.

Add the rule on your hosting platform

Choose the configuration that matches where your site runs.

Add a rewrite in next.config.js, next.config.mjs, or next.config.ts:

export default {
  async rewrites() {
    return [
      {
        source: "/stats/:path*",
        destination: "https://dash.tinyanalytics.io/:path*",
      },
    ];
  },
};

On a managed host, continue to the visitor-IP step below. If you run Next.js behind your own Nginx or Caddy server, proxy there instead so the visitor header is explicit.

Add the rewrite to vercel.json:

{
  "rewrites": [
    {
      "source": "/stats/:path*",
      "destination": "https://dash.tinyanalytics.io/:path*"
    }
  ]
}

Add a forced proxy rewrite to netlify.toml:

[[redirects]]
  from = "/stats/*"
  to = "https://dash.tinyanalytics.io/:splat"
  status = 200
  force = true

Add a location block. The trailing slash on proxy_pass removes the /stats/ prefix:

location /stats/ {
    proxy_pass https://dash.tinyanalytics.io/;
    proxy_ssl_server_name on;
    proxy_set_header Host dash.tinyanalytics.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Use handle_path to remove the prefix before forwarding:

yourdomain.com {
  handle_path /stats/* {
    reverse_proxy https://dash.tinyanalytics.io {
      header_up Host dash.tinyanalytics.io
      header_up X-Real-IP {remote_host}
    }
  }

  # Your site's other routes.
}

Bind a Worker to yourdomain.com/stats/* and forward Cloudflare’s verified visitor address as X-Real-IP:

export default {
  async fetch(request) {
    const incoming = new URL(request.url);
    const upstream = new URL(
      incoming.pathname.replace(/^\/stats/, "") + incoming.search,
      "https://dash.tinyanalytics.io",
    );

    const headers = new Headers(request.headers);
    const visitorIp = request.headers.get("CF-Connecting-IP");
    if (visitorIp) {
      headers.set("X-Real-IP", visitorIp);
      headers.set("X-Forwarded-For", visitorIp);
    }

    return fetch(upstream, {
      method: request.method,
      headers,
      body: ["GET", "HEAD"].includes(request.method) ? undefined : request.body,
    });
  },
};

Configure the equivalent of these four rules:

Match https://yourdomain.com/stats/*.
Remove /stats and forward the rest to https://dash.tinyanalytics.io.
Preserve the method, body, Content-Type, User-Agent, and response headers.
Set X-Real-IP to the visitor’s address, or preserve it as the first X-Forwarded-For entry and use the dashboard setting in the next step.

Preserve the visitor address

Prefer setting X-Real-IP to the address your hosting edge or reverse proxy verified. This keeps cookieless visitor counts, location, device context, and bot detection tied to the visitor rather than your proxy server.If your platform can only preserve the visitor as the first X-Forwarded-For entry, open Settings → Exclusions for the site and turn on First-party proxy. That setting makes TinyAnalytics prefer the first forwarded address over the address of its own Cloudflare edge.

Leave First-party proxy off when you are not using this topology. A browser can forge X-Forwarded-For unless a trusted proxy replaces or appends it, so enabling the setting on a direct tracking setup would let visitors spoof their address.

Generate and deploy the proxied tracking script

In TinyAnalytics, open Settings → Tracking and enter the full prefix URL in Custom Domain (Proxy), for example https://yourdomain.com/stats. Copy the regenerated tag and replace the existing tracking script on your site:

<script
  src="https://yourdomain.com/stats/script.js"
  data-site-id="123"
  defer
></script>

The tracker derives https://yourdomain.com/stats from its own src, so pageviews and other browser requests use the same prefix automatically. The dashboard field composes the tag; the deployed tag is the configuration, so publish your site after you copy it.

What does the proxy forward?

A prefix-wide wildcard keeps the setup current as you enable optional tracker features. These are the current browser-facing paths:

Paths after your prefix	When they are used
`/script.js`, `/api/track`	Every tracked site.
`/api/identify`, `/api/group-identify`	User identification, traits, and group analytics.
`/script-vitals.js`	Web Vitals collection.
`/api/site/:siteId/tracking-config`, `/api/site/:siteId/feature-flags/evaluate`, `/script-surveys.js`	Feature flags and surveys.
`/script-heatmap.js`, `/api/heatmap`	Click and rage-click heatmaps.
`/script-replay.js`, `/api/replay`	Session replay recording.

You do not need to list these paths separately when your /stats/* rule strips the prefix and forwards the remaining path unchanged. Preserve OPTIONS requests and upstream response headers if you use a subdomain instead of a same-origin path.

Allow the proxied paths in a Content-Security-Policy

If your site sends a Content-Security-Policy, the browser must be allowed to load tracker scripts from your prefix and to send analytics requests to it. Two directives matter:

script-src covers script.js and the lazy feature scripts the tracker loads from the same host — including the session replay recorder /script-replay.js.
connect-src covers the tracker’s POST requests — /api/track, /api/heatmap, /api/replay, and the other API paths in the table above.

With a same-origin prefix such as /stats, 'self' covers both directives:

Content-Security-Policy: script-src 'self'; connect-src 'self'

If you proxy on a subdomain instead of a path, list that origin explicitly in both directives:

Content-Security-Policy: script-src 'self' https://stats.yourdomain.com; connect-src 'self' https://stats.yourdomain.com

Without a proxy, the same two directives must allow https://dash.tinyanalytics.io. A policy that only allows the script host but not the connect host loads the tracker and then silently drops every event — and blocks replay uploads — so always update both together.

Use split delivery with `data-api-host`

The full proxy above is recommended because TinyAnalytics updates the tracking script without any work on your side. If you intentionally keep a copy of script.js in your own static assets, set data-api-host so events and lazy feature scripts still use your proxy:

<script
  src="/vendor/tinyanalytics.js"
  data-site-id="123"
  data-api-host="https://yourdomain.com/stats"
  defer
></script>

In this mode, you own the static copy and must replace it when the hosted tracking script changes. The prefix-wide proxy rule is still useful because Web Vitals, surveys, heatmaps, and feature gates load from data-api-host at runtime.

Troubleshooting

Symptom	Cause and fix
The script URL returns `404`	The rule did not strip the prefix. `/stats/script.js` must reach upstream `/script.js`.
The script loads but no events arrive	The rule covers only the script. Forward the whole `/stats/*` prefix so `/api/track` reaches TinyAnalytics.
A real `/api/track` request returns `400`	The proxy changed the body or `Content-Type`. Forward both without rewriting.
Visitors appear in one location or collapse into too few users	The proxy address is being used. Set `X-Real-IP`, or preserve the visitor as the first `X-Forwarded-For` entry and enable First-party proxy.
Optional features call `dash.tinyanalytics.io` directly	You copied the script locally without `data-api-host`, or the prefix does not cover the lazy script and feature-gate paths.
The browser reports a CORS error	Prefer a path on the tracked domain. For a proxy subdomain, forward `OPTIONS` and preserve TinyAnalytics response headers.
The console shows `Refused to load the script` or `Refused to connect`	Your Content-Security-Policy does not allow the proxied origin in `script-src` or `connect-src`. See the CSP section.

Verify the proxy

Check the tracking script route

Confirm the proxied script returns JavaScript:

curl -sI https://yourdomain.com/stats/script.js

Expect 200 and a JavaScript Content-Type.

Observe a browser event

Open your deployed site with browser developer tools, filter the Network panel by /stats, and navigate once. script.js should return 200, and the browser’s /stats/api/track request should return 204. A 404, 405, or HTML response means the proxy did not preserve the path or method. If you use heatmaps, surveys, flags, or Web Vitals, their optional requests should use the same prefix.

Verify attribution

Open Realtime analytics. Your visit should appear within seconds with your network’s location rather than the proxy server’s location. Repeat from another network if you need to confirm that visitor identity is not collapsing onto the proxy address.

The proxy is working when the tracking script loads from your domain, real events return 204 through the prefix, and Realtime shows the visitor’s location rather than the proxy’s.

Install the tracking script

Add the standard tag before switching its source to your proxy.

Configure the tracking script

Use data-api-host and the other supported script attributes.

Exclude traffic

Understand the First-party proxy IP-precedence setting.

Verify your setup

Diagnose a missing pageview or event.

Start here

Set up tracking

Collect data

Web Analytics

Product Analytics

Account & Data Imports

Set up a first-party analytics proxy

Prerequisites

Configure the proxy

What does the proxy forward?

Allow the proxied paths in a Content-Security-Policy

Use split delivery with `data-api-host`

Troubleshooting

Verify the proxy

Install the tracking script

Configure the tracking script

Exclude traffic

Verify your setup

​Prerequisites

​Configure the proxy

​What does the proxy forward?

​Allow the proxied paths in a Content-Security-Policy

​Use split delivery with data-api-host

​Troubleshooting

​Verify the proxy

​Related

Install the tracking script

Configure the tracking script

Exclude traffic

Verify your setup

Prerequisites

Configure the proxy

What does the proxy forward?

Allow the proxied paths in a Content-Security-Policy

Use split delivery with `data-api-host`

Troubleshooting

Verify the proxy

Related