fix(consent): bypass Shopify privacy banner SDK on subdomain-checkout setups

[paul-phan]

Problem

On any Hydrogen storefront with a checkout subdomain (the standard setup — storefront on the apex, checkout on a subdomain like checkout.mystore.com), Shopify's hosted privacy banner is broken:

• Banner reappears on every refresh
• Google Consent Mode v2 status reverts G111 (granted) → G100 (denied) on the second page view
• DevTools shows POST https://.mystore.com/api/unstable/graphql.json net::ERR_NAME_NOT_RESOLVED
• window.Shopify.customerPrivacy.setTrackingConsent is undefined after the banner script loads

Root cause

Hydrogen passes the Shopify Customer Privacy SDK a config field storefrontRootDomain derived from "." + commonAncestorDomain(checkoutDomain, location.host). The leading dot is intentional and only meant for cookie Domain= scoping so the consent cookie is readable across subdomains.

But both storefront-banner.js and the underlying consent-tracking-api.js (v0.1 and v0.2) take this same string and use it as a URL hostname for an SFAPI POST that records the consent decision:

https://.mystore.com/api/unstable/graphql.json
       ^
       leading dot — invalid hostname → DNS fails

In the banner-script case the SDK init crashes before installing setTrackingConsent / currentVisitorConsent on window.Shopify.customerPrivacy. In the core SDK case the cookie write is chained after the failed fetch's .then(), so _tracking_consent is never persisted either way.

Hydrogen has no public prop to override this. The relevant comment in @shopify/hydrogen/dist/development/index.cjs already acknowledges the underlying limitation:

"Once consent-tracking-api is updated to not rely on cookies anymore, we can remove this."

Fix

withPrivacyBanner: false in the root loader's consent config skips loading the broken banner script. Only the core consent-tracking-api.js loads.

Then a minimal custom <ConsentBanner /> component:

• Renders on absence of _tracking_consent cookie (the canonical first-visit signal — shouldShowBanner() in v0.2 is gated on a server display_banner flag that Hydrogen never triggers, not interaction state).

• On Accept / Decline writes _tracking_consent directly with the exact format Shopify expects. Format reverse-engineered from the SDK source — a custom serializer (NOT JSON.stringify): unquoted object keys, JSON.stringify for strings, toString for booleans/numbers, omits undefined and empty-string fields. Example payload:

  {v:"3",con:{CMP:{a:"1",p:"1",m:"1",s:"0"}},cus:{},purposes:{p:false,a:false,m:false,t:false},sale_of_data_region:false,display_banner:false,consent_id:"<uuid>"}
  

• Sets Domain=.mystore.com so the Shopify checkout reads the same cookie and honors it.

• Dispatches visitorConsentCollected on window with the same VisitorConsentCollected shape Shopify's SDK emits, so anything listening (Google Consent Mode v2 updaters, custom analytics wiring, etc.) keeps working unchanged.

Reverting when Shopify fixes the SDK

Three steps:

1. Flip withPrivacyBanner: false → true in app/.server/root.ts.
2. Delete app/components/root/consent-banner.tsx.
3. Remove the import + mount line in app/root.tsx.

Verification

Tested on a production Hydrogen 2026.4 storefront with the same checkout-subdomain setup:

• Before: _tracking_consent absent in cookies after clicking Accept; GA4 collect URL gcs=G100 after refresh.
• After: _tracking_consent written with Domain=.mystore.com, 365-day expiry, format byte-compatible with the SDK's writer; banner does not reappear on refresh; GA4 collect URL stays gcs=G111; Shopify checkout honors the consent.

Files changed

• app/.server/root.ts — withPrivacyBanner: false + a long inline comment documenting why
• app/components/root/consent-banner.tsx (new) — the custom banner UI + cookie writer
• app/root.tsx — import + mount the new component inside the existing <Analytics.Provider>

No new dependencies. ~250 lines net.

No behavioural change for same-domain setups

Storefronts where the checkout lives on the same domain (so storefrontRootDomain has no leading dot) never hit the bug, but they will still render the new banner correctly — it's the same UX, just from a different file.

[paul-phan]

Filed upstream: Shopify/hydrogen#3761 — same root cause analysis, with reproduction steps and code evidence from both broken SDK paths. References this PR as the reference workaround.

When Shopify ships the CDN-side fix (or merges a docs/code change on their end), the 3-step revert procedure in this PR's description stays valid.