diff --git a/_docs/20_install-script/01_script.md b/_docs/20_install-script/01_script.md
index ef7ed5e..59e3139 100644
--- a/_docs/20_install-script/01_script.md
+++ b/_docs/20_install-script/01_script.md
@@ -2,7 +2,7 @@
title: How to add our script
category: install-script
permalink: /script
-last_modified_at: 2026-11-06
+last_modified_at: 2026-11-18
---
## Install with AI
@@ -27,6 +27,16 @@ Include these two lines on every page at the end of your `
` (or anywhere e
We have a website setup wizard to test if you installed your script correctly. If you still have problems installing it, please let us know! We helped a lot of people with setting up their script and we love to help you as well. Just [contact](https://simpleanalytics.com/contact) us.
+## Count AI agents and robots (beta)
+
+AI agents, like ChatGPT-User, and robots request your pages without running the script. To count them too, your website's server can report its page requests with server-side collection. Using an AI agent? Ask it:
+
+```
+Set up Simple Analytics server-side collection for example.com, follow https://docs.simpleanalytics.com/server-side-collection.md
+```
+
+To set it up yourself, see [server-side collection](/server-side-collection).
+
## Server-side tracking
We support server-side tracking, [read more about it here](/events/server-side#page-view-data-structure).
diff --git a/_docs/20_install-script/06_server-side-collection.md b/_docs/20_install-script/06_server-side-collection.md
new file mode 100644
index 0000000..1980e72
--- /dev/null
+++ b/_docs/20_install-script/06_server-side-collection.md
@@ -0,0 +1,46 @@
+---
+title: Server-side collection (beta)
+category: install-script
+permalink: /server-side-collection
+last_modified_at: 2026-11-18
+created_at: 2026-11-18
+---
+
+AI agents and robots request your pages without running the script, so the script can't count them. With server-side collection, your website's server reports the page requests it answers to Simple Analytics, and we decide whether an AI agent, a robot or a person made each one. Requests from people are discarded right away, because the script already counts them, so keep the script on your website.
+
+- **AI agents,** like ChatGPT-User and Claude-User fetching your page because someone asked an AI product, show up in your reports and count toward your usage. Your numbers go up when you set it up.
+- **Robots,** like Googlebot, GPTBot and curl, are stored but hidden by default, and don't count toward your usage.
+- **No token or setting:** the small piece of code on your server, the integration, is all you need.
+- **Privacy:** your server sends the addresses of a request, which we use in memory only and never store or log. It never sends cookies or authorization headers, and only the query parameters you allow.
+
+> **Beta:** the beta covers how we classify and show AI agents and robots. What your integration sends is fixed, so it keeps working after the beta.
+
+## Install with AI
+
+Using Claude Code, Codex, Cursor or another AI agent? Let it write the integration and test it. In the dashboard, your website's settings have **Copy AI instructions** for server-side collection, with your hostname filled in. Paste them into your agent. Or ask your agent:
+
+```
+Set up Simple Analytics server-side collection for example.com, follow https://docs.simpleanalytics.com/server-side-collection.md
+```
+
+The agent asks you which query parameters to report, tells you which pages it can't count, and tests the integration without storing anything. Nothing is sent to us automatically: when something doesn't work, the agent gives you a list to send to [our support](https://simpleanalytics.com/contact).
+
+## Install with Next.js
+
+{% include server-side-collection/nextjs.md %}
+
+## Install on other frameworks
+
+Your integration has to send exactly what's described here. [The guide for AI agents](/server-side-collection.md) has the same rules, with the steps around them.
+
+{% include server-side-collection/integration.md %}
+
+## Pages that are not counted
+
+{% include server-side-collection/not-counted.md %}
+
+## Test it
+
+{% include server-side-collection/tests.md %}
+
+Need help? Send us what you tried through [our support channels](https://simpleanalytics.com/contact).
diff --git a/_docs/31_integrations/03_next.md b/_docs/31_integrations/03_next.md
index d1722f0..aeb68e3 100644
--- a/_docs/31_integrations/03_next.md
+++ b/_docs/31_integrations/03_next.md
@@ -3,7 +3,7 @@ title: Install Simple Analytics with Next.js
menu: Next.js
category: integrations
permalink: /install-simple-analytics-with-next
-last_modified_at: 2026-11-13
+last_modified_at: 2026-11-18
---
We recommend using the official **Simple Analytics for Next.js** plugin (`@simpleanalytics/next`). It provides cookie-less analytics, request proxying to avoid ad blockers, and event tracking on both client and server.
@@ -93,6 +93,16 @@ The `SimpleAnalytics` component collects pageviews automatically. For manual tra
```
+### Counting AI agents and robots (beta)
+
+AI agents and robots request your pages without running the script. `trackRequest` reports page requests from `proxy.ts` (`middleware.ts` before Next.js 16), so they are counted too. Using an AI agent? Ask it:
+
+```
+Set up Simple Analytics server-side collection for example.com, follow https://docs.simpleanalytics.com/server-side-collection.md
+```
+
+To set it up yourself, see [server-side collection](/server-side-collection#install-with-nextjs).
+
### Tracking pageviews server-side
Simple Analytics infers the visitor’s country from their time zone. On the server you don’t have that by default, but some hosts (e.g. [Vercel](https://vercel.com/docs/edge-network/headers/request-headers), [Cloudflare](https://developers.cloudflare.com/rules/transform/managed-transforms/reference/), [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html)) send the visitor’s time zone in request headers. If present, it is included in the data sent to Simple Analytics unless you ignore it.
diff --git a/_includes/server-side-collection/integration.md b/_includes/server-side-collection/integration.md
new file mode 100644
index 0000000..15a528a
--- /dev/null
+++ b/_includes/server-side-collection/integration.md
@@ -0,0 +1,130 @@
+Write the integration in the website's own code and language. Use the standard library or an HTTP client the app already has, and keep it in one small piece of code, like a middleware, plus its configuration.
+
+### Where it runs
+
+Run it for every request, in a middleware, filter or hook that sees the request and, when the framework allows it, the response. It must never make a page slower or break it, so report a request after the response is sent, or alongside it:
+
+- Use the framework's hook for work after the response when it has one, like the `terminate` method of a Laravel middleware, `res.on("finish")` in Express or `rack.after_reply` in Puma. In plain PHP, call `fastcgi_finish_request()` first when it exists.
+- On serverless platforms the code stops when the response is sent, so hand the report to the platform's `waitUntil`, like `ctx.waitUntil` in Cloudflare Workers or `waitUntil` from `@vercel/functions` on Vercel.
+- Otherwise start it in the background without waiting for it, like in a goroutine or a thread pool.
+
+### Configuration
+
+- **Hostname:** the hostname of the website in Simple Analytics, like `example.com`. Keep it in the app's configuration, where its other settings live, as `SIMPLE_ANALYTICS_HOSTNAME` when the app uses environment variables. Never read it from the request's `Host` header. Without a hostname the integration does nothing, so leave it empty on staging and preview deployments.
+- **Extra query parameters:** the parameters to report besides the default ones, empty unless the website needs more.
+- **Test mode:** off by default, on when the environment variable `SIMPLE_ANALYTICS_TEST_MODE` is `1` or `true`. See test mode below.
+
+Outside test mode, report only from production, the way the app already tells production apart, like `NODE_ENV`, `APP_ENV`, `RAILS_ENV` or Django's `DEBUG`. Otherwise the requests you make while developing are recorded too.
+
+### Which requests it reports
+
+Report a request only when all of these are true:
+
+1. Its method is `GET`.
+2. Its path doesn't end in the file extension of a stylesheet, JavaScript, image, font, audio, video or JSON file, in any case: `.css`, `.js`, `.mjs`, `.cjs`, `.apng`, `.avif`, `.bmp`, `.gif`, `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.tif`, `.tiff`, `.webp`, `.eot`, `.otf`, `.ttf`, `.woff`, `.woff2`, `.aac`, `.flac`, `.m4a`, `.mp3`, `.oga`, `.ogg`, `.opus`, `.wav`, `.weba`, `.m4v`, `.mov`, `.mp4`, `.ogv`, `.webm`, `.json`, `.map` or `.webmanifest`.
+3. When the integration sees the response: its status is `200`, and its media type isn't one of those either: `text/css`, `text/javascript`, `application/javascript`, anything that starts with `image/`, `font/`, `audio/` or `video/`, `application/json`, or anything that ends in `+json`. The media type is the part before any `;` of the response's `Content-Type`, trimmed and compared case-insensitively, so `application/json; charset=utf-8` and `Text/CSS` are skipped and `text/html; charset=utf-8` is reported.
+
+Pages are reported, also `.html`, `.txt`, `.xml` and `.pdf` files. Don't filter on anything else: no lists of user agents or addresses, and no checks of other request headers. Simple Analytics decides who made each request, so the requests of people are sent too.
+
+### What it sends
+
+One `POST` request to `https://queue.simpleanalyticscdn.com/requests`, with the header `Content-Type: application/json` and one flat JSON object as its body:
+
+```json
+{
+ "version": 1,
+ "platform": "laravel",
+ "hostname": "example.com",
+ "path": "/pricing",
+ "query": "utm_source=chatgpt.com",
+ "status": 200,
+ "content_type": "text/html; charset=utf-8",
+ "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot",
+ "referer": "https://chatgpt.com/",
+ "accept": "text/html,application/xhtml+xml",
+ "accept_language": "en-US",
+ "sec_fetch_mode": "navigate"
+}
+```
+
+| Field | Sent | Value |
+| --- | --- | --- |
+| `version` | Always | The number `1` |
+| `platform` | Always | The framework, or the runtime or language when there is no framework, in lower case letters, digits and hyphens: `laravel`, `symfony`, `wordpress`, `php`, `django`, `flask`, `fastapi`, `python`, `rails`, `sinatra`, `ruby`, `express`, `fastify`, `nestjs`, `hono`, `sveltekit`, `nuxt`, `astro`, `remix`, `nodejs`, `cloudflare-workers`, `phoenix`, `go`, `aspnet`, `spring` and so on. `nextjs` is for the Next.js package. |
+| `hostname` | Always | The hostname from the configuration |
+| `path` | Always | The path the visitor requested, in full: it starts with `/`, includes any prefix the app is served under, has no query string, and keeps the percent-encoding of the request. Not a route pattern. |
+| `query` | When at least one allowed parameter is present | Only the allowed query parameters, in the order they came in, as `name=value` pairs joined by `&`, percent-encoded and without `?`. Leave the field out when none is present. Other parameters, like tokens, never leave the server. |
+| `status` | When the integration sees the response | The number `200`, because only those are reported |
+| `content_type` | When the integration sees the response | The response's `Content-Type` header, unchanged |
+| `test` | In test mode only | `true` |
+| Copied request headers | When the request has the header, even when it's empty | The header's value, unchanged, under the field in the table below |
+
+The allowed query parameters are `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `source`, `medium`, `campaign`, `content`, `term` and `ref`, plus the extra ones from the configuration. Names must match exactly. A parameter that appears twice is sent twice.
+
+| Field | Request header |
+| --- | --- |
+| `user_agent` | `User-Agent` |
+| `referer` | `Referer` |
+| `accept` | `Accept` |
+| `accept_language` | `Accept-Language` |
+| `sec_fetch_mode` | `Sec-Fetch-Mode` |
+| `sec_fetch_dest` | `Sec-Fetch-Dest` |
+| `sec_fetch_site` | `Sec-Fetch-Site` |
+| `sec_fetch_user` | `Sec-Fetch-User` |
+| `sec_ch_ua` | `Sec-CH-UA` |
+| `signature_agent` | `Signature-Agent` |
+| `from` | `From` |
+
+These request headers travel in the body, not as headers, because HTTP clients like Node.js's `fetch` set their own `User-Agent`, `Accept`, `Accept-Language` and `Sec-Fetch-Mode`. Send no other fields: never cookies, the `Authorization` header, other request headers, the full URL or addresses in the body.
+
+### Addresses
+
+The request to Simple Analytics carries the visitor's addresses in its headers:
+
+- **`X-Forwarded-For`:** the `X-Forwarded-For` header of the incoming request, unchanged, then `, ` and the address of the connection the request came in on. Without an incoming header, only the address of the connection. Don't remove, reorder or check entries, and add nothing else, because Simple Analytics needs the order to tell the visitor apart from proxies.
+- **`CF-Connecting-IP` and `True-Client-IP`:** when the incoming request has them, pass them on unchanged, under the same names.
+
+Send no other headers of the incoming request: never `Cookie` or `Authorization`.
+
+The address of the connection is the address at the other end of the network connection, without a port, like `req.socket.remoteAddress` in Node.js, `$_SERVER['REMOTE_ADDR']` in PHP, `request.META["REMOTE_ADDR"]` in Django, `request.remote_addr` in Rails or the address part of `r.RemoteAddr` in Go. Helpers that take the visitor's address from `X-Forwarded-For` give the wrong value, like `req.ip` in Express, `$request->ip()` in Laravel or `request.remote_ip` in Rails. When the app has middleware that replaces the connection's address or `X-Forwarded-For`, like Flask's `ProxyFix`, the proxy headers of Uvicorn or the forwarded headers middleware of ASP.NET Core, read the original values it keeps, or read them before it runs.
+
+When the code gets no connection address, like behind a Unix socket or on a serverless platform, send the incoming `X-Forwarded-For` unchanged:
+
+- **Vercel functions:** Vercel [sets `X-Forwarded-For`](https://vercel.com/docs/headers/request-headers#x-forwarded-for) to the address of the client that made the request.
+- **Cloudflare Workers:** Cloudflare documents that [`CF-Connecting-IP`](https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-connecting-ip) holds the client's address, and that a Worker [controls the `CF-Connecting-IP`](https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-connecting-ip-in-worker-subrequests) it sends to a destination outside Cloudflare. Pass it on. Cloudflare doesn't document whether an `X-Forwarded-For` header a Worker sets arrives unchanged, so say so in your report.
+
+Simple Analytics uses these addresses in memory only and never stores or logs them.
+
+### How it sends
+
+- **One attempt** that gives up after 2 seconds, reading the reply included, like with `AbortSignal.timeout(2000)` in JavaScript or a 2 second timeout on the HTTP client. Never retry, queue or batch reports.
+- **Errors are swallowed:** catch every error, timeouts too, and carry on. A failed report never changes the response.
+- **Silent:** outside test mode, log nothing: no errors, addresses, headers or replies.
+- **Any reply is fine:** `202` with an empty body means Simple Analytics accepted the request, whether it stores it or not. `400` means the payload is wrong. Outside test mode, don't read the reply.
+
+### Test mode
+
+Test mode lets you check the integration without storing anything. When it's on:
+
+1. Add `"test": true` to the body. Simple Analytics then stores nothing, and replies `200` with JSON that says what it would store.
+2. Report requests also outside production, so it works on a development computer.
+3. Wait for the reply, still at most 2 seconds, and print one block to the server's console or log, in this form:
+
+ ```
+ Simple Analytics test mode: sent {"version":1,"platform":"express","hostname":"example.com","path":"/","test":true,...}
+ with address headers {"X-Forwarded-For":"127.0.0.1"}
+ queue replied 200: {"test":true,"outcome":"ai_agent","name":"ChatGPT-User",...}
+ ```
+
+ When the request fails, print `Simple Analytics test mode: the request was not reported:` and the error.
+4. Never print the incoming URL or other request headers, so tokens in them stay out of the log.
+
+The reply has these fields:
+
+- `outcome`: `ai_agent`, `robot`, `person` or `health_checker`. People and health checkers, like `kube-probe`, are never stored.
+- `name`: the name Simple Analytics would store, like `ChatGPT-User`, `Googlebot`, `curl` or `Unidentified`, the health checker's name, or `null` for a person.
+- `reason`: why, like `ai_agent_name`, `robot_name`, `robot_word`, `not_a_browser`, `datacenter_addresses`, `health_checker` or `person`.
+- `would_store`: the page view it would store, without addresses, or `null`.
+- `addresses`: each address it received, the header it came in, what it belongs to (`private`, `own_proxy`, `cdn`, `datacenter` or `other`), and whether it was judged.
+
+An invalid payload gets `400` with `errors`, a list of what is wrong. Test mode prints visitors' addresses and stores nothing, so it's never on in production.
diff --git a/_includes/server-side-collection/nextjs.md b/_includes/server-side-collection/nextjs.md
new file mode 100644
index 0000000..31eba71
--- /dev/null
+++ b/_includes/server-side-collection/nextjs.md
@@ -0,0 +1,28 @@
+Use `trackRequest` from [`@simpleanalytics/next`](https://www.npmjs.com/package/@simpleanalytics/next), version 1.2.0 or later, instead of writing an integration. It sends the same payload and addresses. It runs before Next.js answers, so it doesn't know the response: it sends no `status` or `content_type`, and it also reports pages that don't exist.
+
+1. Install or update the package with the project's package manager, like `npm install @simpleanalytics/next@latest`.
+2. Set these environment variables for the production deployment. Server-side collection is off until the second one is set, and removing it turns it off again:
+
+ ```sh
+ SIMPLE_ANALYTICS_HOSTNAME=example.com
+ SIMPLE_ANALYTICS_SERVER_SIDE_COLLECTION=1
+ ```
+
+3. Call `trackRequest` in `proxy.ts`, or in `middleware.ts` before Next.js 16, next to the `app` or `pages` folder. When the file exists, add the `event.waitUntil` line at the top of its function and keep the rest. When it has a `matcher`, make sure it matches every page.
+
+ ```ts
+ import { type NextFetchEvent, type NextRequest, NextResponse } from "next/server";
+ import { trackRequest } from "@simpleanalytics/next/server";
+
+ export function proxy(request: NextRequest, event: NextFetchEvent) {
+ event.waitUntil(trackRequest({ request }));
+
+ return NextResponse.next();
+ }
+ ```
+
+ In `middleware.ts` the function is called `middleware` instead of `proxy`.
+
+4. To report query parameters besides the default ones, add them as `allowParams`, like `trackRequest({ request, allowParams: ["promo"] })`.
+
+Test mode is on when `SIMPLE_ANALYTICS_TEST_MODE` is `1`. It asks Simple Analytics to store nothing, works under `next dev`, and prints what was sent and the reply on the server console. A static export (`output: "export"`) has no server, so `trackRequest` never runs there. See also [the package's documentation](https://simpleanalytics-next-docs.vercel.app/docs/server-side-collection).
diff --git a/_includes/server-side-collection/not-counted.md b/_includes/server-side-collection/not-counted.md
new file mode 100644
index 0000000..a1891e9
--- /dev/null
+++ b/_includes/server-side-collection/not-counted.md
@@ -0,0 +1,8 @@
+An integration only sees the requests that reach the website's server. These pages are not counted, and there's no fix for them yet:
+
+- **Pages a CDN or cache in front of the server answers,** like Cloudflare, Fastly or CloudFront when they cache pages and not only files, Varnish, or the `proxy_cache` of Nginx.
+- **Pages the web server answers without the app,** like HTML files that Nginx or Apache serve from disk, or a full-page cache that answers before the app's code runs, which many WordPress caching plugins do.
+- **Websites without a server,** like static exports, GitHub Pages, or files on a CDN or in a storage bucket.
+- **Responses other than `200`,** like `304 Not Modified` when a browser or robot checks a page it already has.
+
+With Next.js, `trackRequest` runs before the cache of Next.js and Vercel, so their cached and static pages are counted. A CDN in front of Next.js still answers without it.
diff --git a/_includes/server-side-collection/tests.md b/_includes/server-side-collection/tests.md
new file mode 100644
index 0000000..9768f05
--- /dev/null
+++ b/_includes/server-side-collection/tests.md
@@ -0,0 +1,96 @@
+Replay these requests against the app in test mode and compare each reply with the expected one. Test mode stores nothing.
+
+1. Start the app on the development computer with test mode on and the hostname set. For Next.js: `SIMPLE_ANALYTICS_HOSTNAME=example.com SIMPLE_ANALYTICS_SERVER_SIDE_COLLECTION=1 SIMPLE_ANALYTICS_TEST_MODE=1 npm run dev`. For other apps, add `SIMPLE_ANALYTICS_TEST_MODE=1` to the usual start command.
+2. Send the requests from the same computer, straight to the app and not through a proxy or CDN, so the connection's address is a local one. Pick a page that answers `200` with HTML:
+
+ ```sh
+ APP=http://localhost:3000
+ PAGE=/
+ CHROME='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36'
+ ```
+
+3. Send one request at a time. After each, read the `Simple Analytics test mode:` block in the app's console or log, and compare `outcome` and `name` in the reply with the expected ones. Also check what was sent: the fields, the copied headers and `X-Forwarded-For`.
+
+The requests:
+
+1. **ChatGPT-User**, an AI agent. Expect `outcome` `ai_agent` and `name` `ChatGPT-User`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot' "$APP$PAGE"
+ ```
+
+2. **Claude-User**, an AI agent. Expect `outcome` `ai_agent` and `name` `Claude-User`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Claude-User/1.0; +Claude-User@anthropic.com)' "$APP$PAGE"
+ ```
+
+3. **ChatGPT agent**, an AI agent with a normal Chrome user agent and a `Signature-Agent` header. Expect `outcome` `ai_agent` and `name` `ChatGPT agent`.
+
+ ```sh
+ curl -sS -o /dev/null -A "$CHROME" -H 'Signature-Agent: "https://chatgpt.com"' "$APP$PAGE"
+ ```
+
+ The sent body has `signature_agent` with the quotes: `"https://chatgpt.com"`.
+
+4. **Googlebot**, a robot. Expect `outcome` `robot` and `name` `Googlebot`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)' "$APP$PAGE"
+ ```
+
+5. **GPTBot**, an AI crawler, which is a robot. Expect `outcome` `robot` and `name` `GPTBot`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GPTBot/1.3; +https://openai.com/gptbot)' "$APP$PAGE"
+ ```
+
+6. **curl** with its own user agent, a robot. Expect `outcome` `robot` and `name` `curl`.
+
+ ```sh
+ curl -sS -o /dev/null "$APP$PAGE"
+ ```
+
+7. **kube-probe**, a health checker. Expect `outcome` `health_checker` and `name` `kube-probe`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'kube-probe/1.33' "$APP$PAGE"
+ ```
+
+8. **A person in Chrome.** Expect `outcome` `person` and `name` `null`.
+
+ ```sh
+ curl -sS -o /dev/null -A "$CHROME" -H 'Accept: text/html,application/xhtml+xml' -H 'Accept-Language: en-US,en;q=0.9' -H 'Sec-Fetch-Mode: navigate' -H 'Sec-Fetch-Dest: document' -H 'Sec-Fetch-Site: none' -H 'Sec-Fetch-User: ?1' "$APP$PAGE"
+ ```
+
+ The sent body has `accept`, `accept_language`, `sec_fetch_mode`, `sec_fetch_dest`, `sec_fetch_site` and `sec_fetch_user`. A person is discarded. Is it a robot named `Unidentified` instead? Then the app saw a datacenter address as the connection, for example because you reached a cloud machine through its public address.
+
+9. **Chrome from a datacenter address,** a robot. Expect `outcome` `robot` and `name` `Unidentified`.
+
+ ```sh
+ curl -sS -o /dev/null -A "$CHROME" -H 'X-Forwarded-For: 54.145.10.20' "$APP$PAGE"
+ ```
+
+ `54.145.10.20` is in the published addresses of Amazon EC2. The sent `X-Forwarded-For` is `54.145.10.20, ` followed by the local address of the connection, like `54.145.10.20, 127.0.0.1`. With Next.js, and wherever the code gets no connection address, it's `54.145.10.20` alone. When the app adds `CF-Connecting-IP` or `True-Client-IP` itself, or a proxy in front of it changes `X-Forwarded-For`, the reply can differ: its `addresses` show what Simple Analytics received.
+
+10. **Query parameters,** from ChatGPT-User. Expect `outcome` `ai_agent` and `name` `ChatGPT-User`.
+
+ ```sh
+ curl -sS -o /dev/null -A 'ChatGPT-User/1.0' "$APP$PAGE?utm_source=chatgpt.com&token=secret123&ref=docs"
+ ```
+
+ The sent `query` is exactly `utm_source=chatgpt.com&ref=docs`: `token` is never sent, and the printed block doesn't contain `secret123`.
+
+11. **A POST request.** Expect no report: nothing is printed.
+
+ ```sh
+ curl -sS -o /dev/null -X POST -A 'ChatGPT-User/1.0' "$APP$PAGE"
+ ```
+
+12. **An image.** Expect no report: nothing is printed.
+
+ ```sh
+ curl -sS -o /dev/null -A 'ChatGPT-User/1.0' "$APP/favicon.ico"
+ ```
+
+When a reply differs from the expected one, compare what was sent with the rules above and fix the integration. The reply's `reason` and `addresses` explain its decision.
diff --git a/install.txt b/install.txt
index e931f52..8d1adb0 100644
--- a/install.txt
+++ b/install.txt
@@ -73,6 +73,7 @@ If the recent hits show nothing, that doesn't mean the installation failed. A pa
- **URL parameters:** we only keep UTM codes and `ref`. To collect another parameter, like `product-id`, add it to [`data-allow-params`]({{ site.url }}/allow-params) first. It's only collected from then on.
- **No personal data:** never put email addresses, names, user IDs or other personal data in paths, URL parameters, [events]({{ site.url }}/events) or [metadata]({{ site.url }}/metadata). It's not allowed, and the account might be suspended.
- **Missing data,** for example because of ad blockers? Set up a [custom domain]({{ site.url }}/bypass-ad-blockers), or even better the [proxy]({{ site.url }}/proxy).
+- **AI agents and robots,** like ChatGPT-User and Googlebot, don't run the script. The website's server can report them with [server-side collection]({{ site.url }}/server-side-collection.md), in beta. It's a separate step: suggest it to the user.
## How the data works
diff --git a/server-side-collection.txt b/server-side-collection.txt
new file mode 100644
index 0000000..00641e2
--- /dev/null
+++ b/server-side-collection.txt
@@ -0,0 +1,66 @@
+---
+layout: null
+permalink: /server-side-collection.md
+sitemap: false
+---
+# Set up server-side collection with Simple Analytics (beta)
+
+How to make a website's own server report its page requests to Simple Analytics, so AI agents and robots that don't run the script are counted too, and how to test it. Written for AI agents, like Claude Code, Codex and Cursor, and for developers.
+
+Server-side collection is in beta. The beta covers how Simple Analytics classifies and shows these page requests. What the integration sends, described below, is fixed: it can only gain optional fields later, so an integration written today keeps working. Follow it exactly.
+
+Came here from the Simple Analytics dashboard? Its instructions gave you the hostname of the website, use it.
+
+## How it works
+
+- The script counts people. AI agents, like ChatGPT-User and Claude-User fetching a page because a person asked an AI product, and robots, like Googlebot, GPTBot and curl, mostly don't run JavaScript, so the script misses them.
+- An integration is a small piece of code on the website's server. For each page request the server answers, it sends a description of the request to Simple Analytics, which decides who made it. AI agents and robots are stored. Requests from people are discarded right away, because the script already counts them.
+- Keep the script. Server-side collection adds to it and doesn't replace it.
+- AI agents show up in the dashboard and count toward the account's usage, so the website's numbers go up. Robots are stored but hidden by default, and don't count toward usage.
+- It needs no token and no setting in Simple Analytics.
+
+## 1. Before you start
+
+1. Find out how the website is served: the framework and language, where it's deployed, and what is in front of it, like Cloudflare, another CDN, a cache or a proxy such as Nginx.
+2. Search the code for `queue.simpleanalyticscdn.com/requests` and `trackRequest`. Is there an integration already? Fix that one instead of adding a second.
+3. Has the website no server, like a static export, GitHub Pages or files on a CDN? Then there's nothing to run an integration. Tell the user that server-side collection isn't possible for it yet, and stop.
+4. Ask the user, in one message, and tell them that AI agents will raise the website's numbers and count toward the account's usage:
+ - The hostname of the website, as it's added in Simple Analytics, like `example.com`. Skip this when you have it.
+ - Which query parameters to report besides `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `source`, `medium`, `campaign`, `content`, `term` and `ref`. No others are sent. Never add parameters that hold tokens, email addresses, names, IDs of people or other personal data.
+
+The hostname goes in the configuration once, and is never read from the request.
+
+## 2. Next.js: use the package
+
+Does the website use Next.js with a server? Follow this step and skip step 3.
+
+{% include server-side-collection/nextjs.md %}
+
+Environment variables only the user can set, like the ones at the hosting provider? Tell the user which ones to set.
+
+## 3. Other frameworks: write the integration
+
+{% include server-side-collection/integration.md %}
+
+## 4. Tell the user which pages are not counted
+
+{% include server-side-collection/not-counted.md %}
+
+Find out which of these apply to the website, like a cache in front of it or HTML files served from disk, and tell the user.
+
+## 5. Test it
+
+{% include server-side-collection/tests.md %}
+
+## 6. Finish
+
+1. Turn test mode off, and make sure it's off in production.
+2. Tell the user:
+ - What you added and where, and how to turn it off.
+ - The query parameters it reports.
+ - Which pages are not counted, from step 4.
+ - Each test request, with the expected and the actual `outcome` and `name`.
+ - What you could not do or check, like settings only the user can change, a CDN you couldn't look into, or a reply that didn't match. Point the user to [Simple Analytics support](https://simpleanalytics.com/contact) for help with those, and give them that list to send.
+3. Nothing is sent to Simple Analytics automatically. Don't contact Simple Analytics yourself, the user decides.
+
+Once the integration runs in production, AI agents show up in the website's reports. Robots are stored but hidden by default.