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

# Cloudflare Workers

> Track AI bot visits and visitors from AI apps on a Cloudflare Worker

The `@aranx/ai-analytics` package wraps the Worker `fetch` handler. 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 with
`ctx.waitUntil`, after the response.

> [!NOTE]
>
> If your site runs on Hono, use the [Hono guide](https://docs.aranx.com/ai-visibility/hono.md). If it is
> a Shopify Hydrogen storefront, use the [Shopify Hydrogen
> guide](https://docs.aranx.com/ai-visibility/shopify-hydrogen.md).

## 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**

```sh theme={null}
npm install @aranx/ai-analytics
```

**2. Add the key as a secret**

```sh theme={null}
npx wrangler secret put ARANX_TRAFFIC_KEY
```

Paste the key when Wrangler asks for it. For `wrangler dev`, add it to
`.dev.vars`:

```sh .dev.vars theme={null}
ARANX_TRAFFIC_KEY=arx_tk_...
```

**3. Wrap the fetch handler**

```ts src/index.ts theme={null}
import { withAiTraffic } from '@aranx/ai-analytics/fetch';

export default {
  fetch: withAiTraffic(async (request, env, ctx) => {
    // Your existing handler
    return new Response('Hello');
  })
};
```

The wrapper reads the key from the `ARANX_TRAFFIC_KEY` binding, and the
client IP from `CF-Connecting-IP`, which Cloudflare sets. Keep the
other handlers (`scheduled`, `queue`) as they are.

**4. Deploy**

```sh theme={null}
npx wrangler deploy
```

## Check the setup

Send a request with an AI user agent:

```sh theme={null}
curl -A "Mozilla/5.0 (compatible; ChatGPT-User/1.0)" https://example.com/
```

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.

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.


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