Skip to main content
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.
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

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:
.env
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.
server.ts
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:
app/lib/env.ts
In a project on Hydrogen 2026-04 or earlier, add it to the global Env interface in env.d.ts:
env.d.ts
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:
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.