Skip to main content
The @aranx/ai-analytics package adds an Express middleware. It records requests from AI bots such as ChatGPT-User and PerplexityBot, and visits from people who open your site from a link in an AI app. It sends events in batches every 10 seconds.

Before you start

  • In Aranx, open AI Visibility for the website and create a server key. Aranx shows the key once.

Setup

1

Install the package

2

Set the key

Set the ARANX_TRAFFIC_KEY environment variable on the server. For local development, add it to .env:
.env
Do not commit the key. The package reads only process.env, so the server must load .env before it creates the middleware. Use node --env-file=.env server.js (Node.js 20.6 or later) or the dotenv loader of the project. Bun loads .env by itself.
3

Add the middleware

Register it before your routes:
server.ts
The client IP is Express’s req.ip. Aranx counts a bot visit only when its IP is in the bot’s published IP ranges. Behind a load balancer, req.ip is the balancer, so set trust proxy for your proxy as the Express guide shows, for example app.set('trust proxy', 1) for one proxy hop. Do not set it to true unless the proxy is the only way to reach the server.
4

Deploy

Deploy the server. Aranx shows the first bot visits on the AI visibility page.

Other Node.js frameworks

Fastify and Koa can pass the Node request to nodeRequestInfo from @aranx/ai-analytics/express with the client IP the framework computed ({ ip: request.ip }, or ctx.ip in Koa), then call tracker.track(info) on a tracker from createAiTraffic().

Check the setup

Send a request with an AI user agent:
Aranx does not count this visit. It counts a bot visit only from an IP in the ranges that OpenAI, Anthropic, and Perplexity publish for their bots, and scanners often fake these user agents. The request still marks the key as used. Wait 10 seconds for the batch. In Aranx, Settings > Sources on the AI visibility page shows when the key was last used.

What the package sends

For each AI request: the page URL without its query (it keeps utm_source), the user agent, the response status, and the time. Bot visits also carry the client IP, which Aranx checks against the bot’s published IP ranges and does not store. Tracking never throws and never delays the response.