Install
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
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:
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):
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 so paid orders count as purchases by people and by agents.
- People in the browser: add the browser 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/mcpthrough your domain are recorded under AI & agents → MCP.
Ask the docs
Answers come from these docs only, written by Claude (Anthropic). Your question is sent to answer it, and isn't stored.