Shopify Unified Tracking: install

Conversion tracking sends storefront views, cart changes and purchases to the ad platforms you configure, once from the browser and once from our servers, with a shared event id so each platform counts them once.

Create a store first

1. Turn on Shopify Tracking on the Gatekeepers page.
2. Open Tracking under Apps, choose New store, name it and pick the storefront type:
   • Hydrogen: npm package plus a checkout pixel, with purchases verified;
   • Online Store theme: one pixel, no code changes, but purchases can’t be verified.
3. You get the store’s key (sut_…). It’s a public identifier that appears in page source; it identifies the store and grants nothing.

Hydrogen storefronts

The Setup tab shows the code with your key filled in. Gosper never edits your code — you make the changes.

1. Install the package

npm install @gosper/hydrogen-tracking

2. server.ts: handle /api/gosper/*

import {withGosperTracking} from '@gosper/hydrogen-tracking/server';

export default withGosperTracking({
  async fetch(request, env, executionContext) {
    // …your existing handler, unchanged
  },
}, {trackingKey: 'sut_…'});

Events go to your own domain first, and your server forwards them to Gosper. Same-origin requests are harder for ad blockers to stop, cookies are first-party, and Safari’s cross-site limits don’t apply.

3. app/root.tsx: inside <Analytics.Provider>

import {GosperTracking} from '@gosper/hydrogen-tracking';

<Analytics.Provider cart={data.cart} shop={data.shop} consent={data.consent}>
  <GosperTracking />
  {/* …your existing layout */}
</Analytics.Provider>

It subscribes to the standard events Hydrogen already publishes: page views, product views, collection views, search, cart views, cart changes, and items added to or removed from the cart.

4. Content Security Policy (when browser pixels are on)

Hydrogen manages the policy with createContentSecurityPolicy, and that stays your code. The management page lists the domains for the platforms you have enabled; add them to your existing options:

const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  shop: {
    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
  },
  defaultSrc: ['https://connect.facebook.net', 'https://www.facebook.com'],
  connectSrc: ['https://connect.facebook.net', 'https://www.facebook.com'],
});

With browser pixels off (Conversions APIs only) no policy change is needed.

5. Deploy, then add the checkout pixel

After deploying, go to Shopify admin → Settings → Customer events → Add custom pixel, paste the checkout pixel from the management page, set Customer privacy to require Marketing, then Save and Connect.

Checkout pages don’t run Hydrogen code, so purchases come from this pixel.

6. Check it

npx gosper-tracking check https://your-store.example

It only requests your public pages and checks that the handler answers, that Gosper recognizes the key, and that your policy allows the domains for your enabled platforms. The Setup checklist on the management page also shows which steps are done.

Theme stores

Paste the full pixel from the management page into Shopify admin → Settings → Customer events → Add custom pixel. It sends both storefront and checkout events.

A theme store has no server of its own to register carts, so purchases carry no proof and aren’t verified by default (see Orders).

Next

Nothing is delivered until you add a platform: Set up ad platforms.