# Install on Shopify Hydrogen

Hydrogen storefronts run their own server code on Shopify's Oxygen, so Punchline goes in as a wrapper around the storefront's request handler. It sees every request, including agents and crawlers that never run JavaScript, and adds nothing to your pages.

## 1. Add the package

```bash
npm install @punchline-analytics/cloudflare
```

Oxygen runs the same kind of handler as a Cloudflare Worker, so it's the Cloudflare package, with a Hydrogen wrapper. Needs 0.6.0 or later.

## 2. Wrap the handler in `server.ts`

Hydrogen's `server.ts` exports `{ fetch(request, env, executionContext) }`. Wrap that function with `withHydrogen`:

```ts
import { withHydrogen } from "@punchline-analytics/cloudflare";

export default withHydrogen(async (rawRequest: Request, env: Env, executionContext: ExecutionContext) => {
  // … the body of your existing fetch handler, unchanged …
});
```

`withHydrogen` reads the shopper's address and country from the headers Oxygen adds (`oxygen-buyer-ip`, `oxygen-buyer-country`). Use it only on Oxygen. On any other host use `withPunchline`, since a client could send those headers itself.

Add the variable to your `Env` type (`env.d.ts`):

```ts
interface Env {
  // … your existing variables …
  PUNCHLINE_DSN?: string;
}
```

## 3. Set the DSN on Oxygen

In Shopify admin: **Hydrogen → your storefront → Storefront settings → Environments and variables → Add variable**. Key `PUNCHLINE_DSN`, value from Site settings → Install in your Punchline dashboard, tick **Make this value secret**, choose the environments (at least Production), and save. Variables apply from the next deployment, so deploy again.

## 4. Check it's working

Visit a few pages of the storefront. They appear in your dashboard within about a minute; **Doctor → Site check** says when the last page view arrived.

## Also for stores

- **Purchases:** add the [order webhook](https://punchlineanalytics.com/docs/install-shopify#3-purchases-the-order-webhook) so paid orders count as purchases by people and by agents.
- **People in the browser:** add the [browser snippet](https://punchlineanalytics.com/docs/install-snippet) to your root layout for in-page navigation and in-browser agent signals.
- **Catalog calls:** agents calling the store's catalog at `/api/ucp/mcp` through your domain are recorded under **AI & agents → MCP**.
