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

# Shopify Hydrogen

> Track AI bot visits and visitors from AI apps on a Hydrogen storefront

The `@aranx/ai-analytics` package wraps the `fetch` handler in the Hydrogen
`server.ts`. It records requests from AI bots such as `ChatGPT-User` and
`PerplexityBot`, and visits from people who open your store from a link in an
AI app. It sends events with `waitUntil`, after the response.

> [!NOTE]
>
> This works for Hydrogen storefronts on Oxygen. A Shopify theme store (Liquid)
> has no server code, so it cannot send bot visits. Connect Cloudflare instead
> if the store's domain is proxied by Cloudflare. Hydrogen in another framework,
> such as Next.js on Vercel, follows the guide for that framework.

## 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 to the storefront**

In Shopify admin, open **Hydrogen**, select the storefront, then open
**Storefront settings > Environments and variables**. Add the variable
`ARANX_TRAFFIC_KEY` with the key as its value, check **Make this value
secret**, and select the environments that get it. A deployment keeps the
variables it had when it was deployed, so deploy after you add the
variable.

For local development, add it to `.env`:

```sh .env theme={null}
ARANX_TRAFFIC_KEY=arx_tk_...
```

**3. Wrap the fetch handler**

In `server.ts`, wrap the existing `fetch` function with `withAiTraffic`.
Keep its parameter names and its body as they are. The React Router
template names the first parameter `rawRequest`. Pass
`{ clientIpHeader: 'oxygen-buyer-ip' }` so the package reads the client
IP from `Oxygen-Buyer-IP`, which Oxygen sets. Without the IP, Aranx does not count
bot visits.

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

export default {
  fetch: withAiTraffic(
    async (
      request: Request,
      env: Env,
      executionContext: ExecutionContext
    ): Promise<Response> => {
      // Your existing handler
    },
    { clientIpHeader: 'oxygen-buyer-ip' }
  )
};
```

The wrapper reads the key from `env.ARANX_TRAFFIC_KEY`. Add the variable
to the `Env` type. In the React Router template (Hydrogen 2026-10 and
later), the type is in `app/lib/env.ts`:

```ts app/lib/env.ts theme={null}
export type Env = {
  // Your existing variables
  ARANX_TRAFFIC_KEY?: string;
};
```

In a project on Hydrogen 2026-04 or earlier, add it to the global `Env`
interface in `env.d.ts`:

```ts env.d.ts theme={null}
declare global {
  interface Env {
    ARANX_TRAFFIC_KEY: string;
  }
}
```

**4. Deploy**

Push to the branch that Oxygen deploys, or deploy with Shopify CLI. In the
React Router template, run `npm run deploy`, which passes the build
directories to `shopify hydrogen deploy`. In a project on Hydrogen 2026-04
or earlier, run `npx shopify hydrogen 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.