@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 The wrapper reads the key from In a project on Hydrogen 2026-04 or earlier, add it to the global
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
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
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:What the package sends
For each AI request: the page URL without its query (it keepsutm_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.
