> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse proxy

> Serve the SDK and send events through your own domain so ad blockers do not drop them. Examples for Next.js, Vercel, Cloudflare Workers and nginx.

Ad blockers and privacy browsers block requests by host and by URL. They block known analytics hosts, and paths that contain words such as `analytics`, `track` or `collect`. With a reverse proxy, the browser talks only to your own site, and your site forwards the requests to the collector.

## What to proxy

| Request | Upstream | Your path (example) |
| - | - | - |
| Events (`POST`) | `https://YOUR_COLLECTOR_ENDPOINT/v0/events` | `/ua/v0/events` |
| SDK script (`GET`, HTML snippet only) | The `src` from your setup page | `/ua.js` |

The SDK sends only `POST <endpoint>/v0/events`. It removes one trailing `/` from the endpoint and appends `/v0/events`. So `data-endpoint="https://yourdomain.com/ua"` posts to `https://yourdomain.com/ua/v0/events`. Proxy that exact path, not the whole API. An npm install bundles the SDK, so it needs only the events path.

Change your snippet to:

```html theme={null}
<script
  src="https://yourdomain.com/ua.js"
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  data-endpoint="https://yourdomain.com/ua"
  defer
></script>
```

For npm installs, set `endpoint: '/ua'` or `endpoint: 'https://yourdomain.com/ua'`.

### Choose a neutral path

Filter lists match URL substrings. Avoid `/analytics.js`, `/track`, `/collect`, `/tracking`, `/stats` and the collector host name. Use a short neutral prefix such as `/ua`, or a name from your own app. The `/v0/events` suffix is fixed.

### Subresource Integrity

If your snippet has `integrity="sha384-..."`, the browser checks the hash against the bytes it receives. A proxy that forwards the same pinned file unchanged keeps the same hash. It fails if the proxy points at a different or unpinned build, or changes the file. Keep `crossorigin="anonymous"`.

## Headers to forward

| Header | Why |
| - | - |
| `Origin` | The collector accepts browser events only from your project domain and its subdomains. |
| `X-Forwarded-For` | The collector looks up the visitor's country from the first public IP. The IP is never stored or logged. |
| `X-Visitor-Country` | Optional. A two-letter country code that overrides the lookup, for example from your edge. |
| `User-Agent` | Device, OS, browser and the bot label |
| `X-Publishable-Key`, `Content-Type` | Authorization and parsing |

The collector does not read `Host`, so it can be any value. If the proxy drops `Origin`, the Publishable key and the page URL domain check still apply.

## Examples

Replace `https://YOUR_COLLECTOR_ENDPOINT` with your collector URL and `SCRIPT_URL` with the `src` from your setup page.

> [tab] Next.js rewrites
>
> ```js theme={null}
> // next.config.js
> module.exports = {
>   async rewrites() {
>     return [
>       // HTML snippet installs only; skip for npm installs.
>       { source: '/ua.js', destination: 'SCRIPT_URL' },
>       { source: '/ua/v0/events', destination: 'https://YOUR_COLLECTOR_ENDPOINT/v0/events' },
>     ];
>   },
> };
> ```
>
> The rewrite forwards the visitor IP in `X-Forwarded-For`. The collector looks up the country from it.

> [tab] Next.js proxy.ts
>
> Next.js 16 renamed Middleware to Proxy. On Next.js 15 and older, name the file `middleware.ts` and the function `middleware`.
>
> ```ts theme={null}
> // proxy.ts (next to app/)
> import { NextResponse, type NextRequest } from 'next/server';
>
> const COLLECTOR = 'https://YOUR_COLLECTOR_ENDPOINT';
>
> export function proxy(request: NextRequest) {
>   const headers = new Headers(request.headers);
>   headers.set('host', new URL(COLLECTOR).host);
>   const country = request.headers.get('x-vercel-ip-country');
>   if (country) headers.set('x-visitor-country', country);
>   return NextResponse.rewrite(new URL('/v0/events', COLLECTOR), { request: { headers } });
> }
>
> export const config = { matcher: '/ua/v0/events' };
> ```

> [tab] Vercel
>
> ```json vercel.json theme={null}
> {
>   "rewrites": [
>     { "source": "/ua.js", "destination": "SCRIPT_URL" },
>     { "source": "/ua/v0/events", "destination": "https://YOUR_COLLECTOR_ENDPOINT/v0/events" }
>   ]
> }
> ```

> [tab] Cloudflare Worker
>
> Attach the Worker to the routes `yourdomain.com/ua.js` and `yourdomain.com/ua/*`.
>
> ```js theme={null}
> const COLLECTOR = 'https://YOUR_COLLECTOR_ENDPOINT';
> const SCRIPT = 'SCRIPT_URL';
>
> export default {
>   async fetch(request) {
>     const url = new URL(request.url);
>     if (url.pathname === '/ua.js') return fetch(SCRIPT, { cf: { cacheEverything: true, cacheTtl: 3600 } });
>     if (url.pathname !== '/ua/v0/events') return new Response('Not found', { status: 404 });
>     const headers = new Headers(request.headers);
>     headers.set('x-forwarded-for', request.headers.get('cf-connecting-ip') ?? '');
>     if (request.cf?.country) headers.set('x-visitor-country', String(request.cf.country));
>     return fetch(`${COLLECTOR}/v0/events`, { method: request.method, headers, body: request.body });
>   },
> };
> ```

> [tab] nginx
>
> ```nginx theme={null}
> location = /ua.js {
>   proxy_pass SCRIPT_URL;
>   proxy_ssl_server_name on;
> }
> location = /ua/v0/events {
>   proxy_pass https://YOUR_COLLECTOR_ENDPOINT/v0/events;
>   proxy_ssl_server_name on;
>   # $remote_addr replaces any value the browser sent.
>   proxy_set_header X-Forwarded-For $remote_addr;
> }
> ```

## Verify

1. Load your site with the browser developer tools open.
2. Confirm that the script loads from `/ua.js` and that `POST /ua/v0/events` returns `202`.
3. Confirm that no request goes to the collector host or the CDN.
4. Open [Activity](https://docs.manalens.dev/features/activity.md). Your events appear with the visitor's country, not `ZZ` (unknown) or the proxy's country.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.