First-party analytics proxy setup and limits

A first-party analytics proxy exposes the browser tracker and event collector under routes on the product's own origin. For example, the browser loads /mf/tracker.js, that loader starts /mf/tracker-runtime.js, and events go to /mf/e; the reverse proxy forwards those exact routes to MetricFold.

The proxy can simplify Content Security Policy, avoid an additional public hostname in the page and make ownership clearer. It does not automatically remove disclosure, consent or data-protection obligations. Those depend on what is collected, why, where it is sent and the applicable law.

Hosted mode requires no Nginx

MetricFold supports a hosted snippet. It loads the deferred tracker from metricfold.com and posts to a site-keyed collector URL. This is the fastest way to begin and is the correct answer when you cannot change server configuration.

The site dashboard shows hosted mode first. Nginx appears only under “Strict first-party proxy.” A proxy is an optional deployment mode, not a prerequisite for a working map, live report or event stream.

Proxy only the documented exact routes

Use exact route matches rather than forwarding a broad prefix. The tracker loader and asynchronously loaded runtime are cacheable public scripts. The collector accepts bounded JSON and must preserve the browser's original Origin value.

An Nginx configuration follows this shape:

location = /mf/tracker.js {
    proxy_pass https://metricfold.com/tracker.js;
    proxy_set_header Host metricfold.com;
    proxy_ssl_server_name on;
}

location = /mf/tracker-runtime.js {
    proxy_pass https://metricfold.com/tracker-runtime.js;
    proxy_set_header Host metricfold.com;
    proxy_ssl_server_name on;
}

location = /mf/e {
    proxy_pass https://metricfold.com/c/YOUR_SITE_KEY/e;
    proxy_set_header Origin $scheme://$host;
    proxy_set_header Content-Type application/json;
}

Use the generated snippet in the site dashboard because it contains the actual site key and current route contract. Do not copy a placeholder into production.

Preserve origin verification

The collector compares the normalized origin with the site's explicit allowlist. Missing, malformed and foreign origins fail closed. A proxy may set the trusted host origin because it operates inside your infrastructure; a public browser must not be able to choose an arbitrary accepted origin header through another route.

Keep the collection endpoint stateless. It does not need an application session, CSRF cookie or queued-cookie middleware. The tracker sends no credentials and the response must not set an analytics cookie.

Cache the script, never the event post

The tracker can use a short public cache duration with revalidation. Event POST responses and live streams must not be cached. Do not place event bodies in access logs. Configure request-body limits at the edge to match or undercut the application limit.

MetricFold's framework-free loader is 0.32 kB gzip and starts the complete runtime asynchronously. Proxying does not make a heavy script light; the browser executes the same bytes. Keep hosted and same-origin modes under the same loader, runtime and interaction-performance gates.

Framework routes follow the same contract

Next.js, Laravel, Cloudflare Workers, Vercel, Netlify and other platforms can implement the two-route boundary. The details differ, but the invariants do not:

1. exact tracker and collector paths;
2. HTTPS upstream with certificate verification;
3. original product origin supplied to MetricFold;
4. no application credentials or cookies forwarded;
5. bounded request and response sizes;
6. no redirects on the event endpoint;
7. cache only the tracker asset;
8. health checks and failure-safe host behavior.

If the analytics upstream is unavailable, the host page still loads and actions still complete. The tracker uses a non-blocking transport and discards the failed delivery rather than delaying navigation.

Verify the installation

After deployment:

• request /mf/tracker.js and confirm JavaScript with the expected cache header;
• send a browser-shaped event from an allowed origin;
• confirm the response has no Set-Cookie header;
• send the same request from a foreign origin and confirm it is rejected or silently dropped by policy;
• inspect the site dashboard for the event under the correct site only;
• run Lighthouse before and after the snippet on the same reference page;
• verify your application logs do not include event bodies or proxy credentials.

The hosted and proxied modes produce the same report. Choose the mode that matches your infrastructure and policy requirements, not the one with the most complicated setup.

Diagnose the common proxy failures

Tracker returns HTML

An application fallback or SPA rewrite may capture /mf/tracker.js and return the homepage. Check the exact-match route order, upstream path and Content-Type. Request the path with curl and confirm the first bytes are JavaScript, not a document. Cache only after the response is correct.

Events arrive with the wrong origin

The collector authorizes the measured site origin. Preserve or deliberately set the product's normalized HTTPS origin at the trusted edge. Do not forward an upstream analytics hostname as the browser origin and do not accept a browser-supplied override through a public query parameter. The MDN Origin header reference explains how browsers express the initiating origin.

POSTs are redirected or cached

Canonical-host and slash redirects can convert or discard a POST. Configure the exact event path on the final host and test it without following redirects. Disable caching for the collector response and ensure a CDN rule cannot cache by URL while ignoring the request body.

The host waits on analytics

Browser analytics must remain non-blocking. The script is deferred and delivery failure cannot prevent navigation or product actions. At the proxy, use bounded connect/read timeouts and avoid retrying an event POST unless the event id makes the upstream operation idempotent.

Apply a production hardening checklist

Use the official Nginx proxy module reference for directive behavior instead of copying an unreviewed snippet. The current site installation manifest remains the source of truth for upstream paths.

1. Match only /mf/tracker.js, /mf/tracker-runtime.js, /mf/e and any explicitly documented plan route.
2. Use HTTPS upstream verification and the correct SNI host.
3. Cap request bodies and reject methods other than those required by each route.
4. Preserve the product origin and do not forward application cookies or authorization headers.
5. Suppress event bodies and sensitive headers from access and error logs.
6. Cache the versioned tracker response; never cache event POSTs or SSE.
7. Set short upstream timeouts and let the measured product succeed independently.
8. Monitor status classes and latency without recording payloads.
9. Test foreign origins, malformed bodies, duplicate ids and upstream failure.
10. Re-run host-page performance and CSP checks after every edge change.

The first-party analytics guide covers the broader governance chain. The cookieless analytics guide explains why proxying does not create a universal consent exemption.

Frequently asked questions

Do I need Nginx to use MetricFold?

No. The hosted deferred snippet works without customer server configuration. Nginx, Cloudflare, Next.js and similar recipes are optional same-origin delivery modes.

Will a proxy make the map work?

No special proxy is required for geography. The collector derives coarse country evidence from trusted deployment headers, and the dashboard renders country geometry independently. A proxy must preserve the required trusted origin and deployment metadata, but it does not provide the map asset.

Can I proxy all MetricFold paths under one prefix?

Do not do that by default. Exact paths make methods, caching, credentials and request limits reviewable. A broad proxy can expose unintended application routes.

What should happen when MetricFold is unavailable?

The host page and product action continue normally. The tracker treats delivery as best-effort, and the proxy uses bounded timeouts. Analytics cannot become a dependency for the measured workflow.

How should a proxy change be released?

Test the generated configuration in a staging host with the real canonical origin and a non-production site key. Validate methods, headers, redirects, request limits, caching and failure timeouts. Run the foreign-origin and duplicate-event cases. Then deploy the exact routes, confirm an accepted event appears in the intended tenant, and inspect host logs for accidental bodies. Keep hosted mode available as a diagnostic path until production is stable.

HTTP semantics such as method preservation, caching and redirects are defined in RFC 9110. Edge behavior should be tested against the chosen implementation rather than inferred from a copied configuration.

After cutover, monitor tracker status, collector status classes and upstream latency without payloads. Alert on sustained failure or unexpected redirects, not individual best-effort delivery loss. Keep the generated manifest version with the deployment so a future route change can be reconciled instead of guessed.

Review that evidence after every infrastructure or collector contract change.