From 0f4e148aebbfea746f5eec502e313f7c16a7479d Mon Sep 17 00:00:00 2001
From: Titouan Mathis <titouan@studiometa.fr>
Date: Wed, 16 Sep 2026 18:28:41 +0200
Subject: [PATCH] feat(track): gate TrackShopify on Shopify analytics consent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`dispatch()` now calls
`window.Shopify.customerPrivacy.analyticsProcessingAllowed()` before every
publish and publishes only when it returns `true`. `window.Shopify` is
read fresh on each dispatch, so a consent change applies to the next
event without a remount.

Shopify's Web Pixels Manager gates App Pixels at load time, but it hands
every published event to custom pixels, which are expected to apply their
own consent logic. That gate is now the component's default instead of
something each storefront repeats before each event.

A dropped event is not queued and is never replayed. Each drop reports a
diagnostic so a missing event is diagnosable: `track.shopify-consent-denied`
when processing is refused, `track.shopify-privacy-unavailable` when the
Customer Privacy API is absent — which is legitimate early in a page's
life, since Shopify loads it asynchronously through `loadFeatures()`.

The event-name check runs before the consent check. A declaration without
an `event` name is wrong for every visitor, so it stays visible instead of
being masked by a consent drop.

The TrackShopify tests move out of `Track.spec.ts` into their own spec.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMSCm41fm3g7chxD728vAu
---
 CHANGELOG.md                                  |   6 +
 packages/docs/.vitepress/reference/catalog.ts |   8 +-
 .../docs/reference/items/Track/anatomy.md     |  12 +-
 .../docs/reference/items/Track/examples.md    |   2 +-
 packages/docs/reference/items/Track/index.md  |  10 +-
 packages/docs/reference/items/Track/js-api.md |  37 ++-
 packages/tests/Track/Track.spec.ts            |  55 +---
 packages/tests/Track/TrackShopify.spec.ts     | 254 ++++++++++++++++++
 packages/ui/src/Track/TrackShopify.ts         |  44 ++-
 9 files changed, 358 insertions(+), 70 deletions(-)
 create mode 100644 packages/tests/Track/TrackShopify.spec.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49fca617..906937f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **TrackShopify:** publish only when Shopify analytics processing is allowed ([#654](https://github.com/studiometa/ui/pull/654))
+
 ## [v2.0.0-alpha.0](https://github.com/studiometa/ui/compare/1.11.1..2.0.0-alpha.0) (2026-09-03)
 
 This is the first release of the v2 line. It moves every package onto [`@studiometa/js-toolkit` v4](https://js-toolkit-v4.studiometa.dev/), removes six component families that a newer component already covers, renames three components, merges `LargeText` and `CircularMarquee` into `Marquee`, rewrites `Tabs` on the WAI-ARIA Tabs pattern, redesigns `Cursor` around published CSS hooks, completes the `Carousel` family and gives it an accessibility contract, and changes the shape of every event payload. There is no compatibility layer.
diff --git a/packages/docs/.vitepress/reference/catalog.ts b/packages/docs/.vitepress/reference/catalog.ts
index b62c9cc2..d5cde4ac 100644
--- a/packages/docs/.vitepress/reference/catalog.ts
+++ b/packages/docs/.vitepress/reference/catalog.ts
@@ -1105,7 +1105,13 @@ export const referenceCatalog = [
       uiSymbol('TrackEvent', '/reference/items/Track/js-api', 'TrackEvent', 'primitive'),
       uiSymbol('TrackShopify', '/reference/items/Track/js-api'),
     ],
-    capabilities: ['click tracking', 'context', 'custom events', 'impression tracking'],
+    capabilities: [
+      'click tracking',
+      'consent gating',
+      'context',
+      'custom events',
+      'impression tracking',
+    ],
   },
   {
     id: 'transition',
diff --git a/packages/docs/reference/items/Track/anatomy.md b/packages/docs/reference/items/Track/anatomy.md
index 4b07d85d..330ece92 100644
--- a/packages/docs/reference/items/Track/anatomy.md
+++ b/packages/docs/reference/items/Track/anatomy.md
@@ -17,12 +17,12 @@ TrackContext                           data-component="TrackContext"   shared, i
 
 ## Parts
 
-| Part              | Selector                        | Required | Role                                                                                       |
-| ----------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
-| Tracker           | `data-component="Track"`        | Yes      | Resolves each `data-track:<event>` payload and pushes it to `window.dataLayer`.            |
-| Tracker (Shopify) | `data-component="TrackShopify"` | Yes\*    | Same as `Track`, but publishes through `window.Shopify.analytics.publish`.                 |
-| Context           | `data-component="TrackContext"` | Optional | Provides data inherited by every descendant tracker, deep-merged up the ancestor chain.    |
-| Payload           | `data-ref="payload"`            | Optional | A `<script>` (or `data-option-payload`) holding data shared by every event on the element. |
+| Part              | Selector                        | Required | Role                                                                                                                              |
+| ----------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Tracker           | `data-component="Track"`        | Yes      | Resolves each `data-track:<event>` payload and pushes it to `window.dataLayer`.                                                   |
+| Tracker (Shopify) | `data-component="TrackShopify"` | Yes\*    | Same as `Track`, but publishes through `window.Shopify.analytics.publish`, and only when the visitor allows analytics processing. |
+| Context           | `data-component="TrackContext"` | Optional | Provides data inherited by every descendant tracker, deep-merged up the ancestor chain.                                           |
+| Payload           | `data-ref="payload"`            | Optional | A `<script>` (or `data-option-payload`) holding data shared by every event on the element.                                        |
 
 <small>\* `Track` and `TrackShopify` are alternative providers — pick the one matching your destination. The provider is chosen by the component name, so switching is a one-token change in the markup.</small>
 
diff --git a/packages/docs/reference/items/Track/examples.md b/packages/docs/reference/items/Track/examples.md
index c5ccae8e..ea7370e3 100644
--- a/packages/docs/reference/items/Track/examples.md
+++ b/packages/docs/reference/items/Track/examples.md
@@ -37,7 +37,7 @@ A product page that sets shared context once, tracks a product impression, and p
 </section>
 ```
 
-The `add_to_cart` click publishes:
+The `add_to_cart` click publishes, when the visitor [allows analytics processing](./js-api.md#consent):
 
 ```js
 Shopify.analytics.publish('my_app:add_to_cart', {
diff --git a/packages/docs/reference/items/Track/index.md b/packages/docs/reference/items/Track/index.md
index 20fa4635..9bbc894b 100644
--- a/packages/docs/reference/items/Track/index.md
+++ b/packages/docs/reference/items/Track/index.md
@@ -7,7 +7,7 @@ badges: [JS]
 The `Track` components provide declarative analytics tracking, defined entirely in HTML/Twig/Liquid attributes — no custom JavaScript required. A provider-agnostic core (`AbstractTrack`) is shipped as two ready-to-use variants selected by component name:
 
 - **`Track`** pushes the resolved payload to `window.dataLayer` (GTM / GA4).
-- **`TrackShopify`** publishes it through `window.Shopify.analytics.publish`.
+- **`TrackShopify`** publishes it through `window.Shopify.analytics.publish`, only when the visitor allows analytics processing.
 
 `TrackContext` lets you factor shared data out of individual events and inherit it from ancestors.
 
@@ -168,6 +168,12 @@ The provider is chosen by the component name, so switching destinations is a one
 
 `TrackShopify` uses the payload's `event` value as the published event name. Shopify recommends namespacing custom events (e.g. `my_app:add_to_cart`). To send to another destination, extend `Track` and override its [`dispatch()`](./js-api.md#providers) method.
 
+## Shopify analytics consent
+
+`TrackShopify` is consent-safe by default. Before each publish it calls `window.Shopify.customerPrivacy.analyticsProcessingAllowed()` and publishes only when that call returns `true`. The check runs on every dispatch, so a consent change applies to the next event without a remount. A denied consent and an absent Customer Privacy API both drop the event — nothing is queued, and each drop reports a diagnostic so the missing event is diagnosable.
+
+Shopify's Web Pixels Manager gates App Pixels at load time, but it hands every published event to custom pixels, which are expected to apply their own consent logic. `Track` is not gated the same way: it appends to `window.dataLayer`, which transmits nothing by itself, so consent there is applied by the tag manager or CMP reading that array. See the [JavaScript API](./js-api.md#consent) for the full behaviour and the diagnostic codes.
+
 ::: warning
-Payloads are serialised into the DOM (attribute or `<script>`), so they are visible in the page source. Never put personal data (emails, names, user IDs) in a tracking payload — resolve sensitive values at runtime via a `CustomEvent` and `$detail.*` instead, and gate `TrackShopify` on the visitor's analytics consent where required.
+Payloads are serialised into the DOM (attribute or `<script>`), so they are visible in the page source. Never put personal data (emails, names, user IDs) in a tracking payload — resolve sensitive values at runtime via a `CustomEvent` and `$detail.*` instead. The components add no customer identifier of their own.
 :::
diff --git a/packages/docs/reference/items/Track/js-api.md b/packages/docs/reference/items/Track/js-api.md
index 4b488704..2dee3f57 100644
--- a/packages/docs/reference/items/Track/js-api.md
+++ b/packages/docs/reference/items/Track/js-api.md
@@ -6,11 +6,11 @@ title: Track JS API
 
 ## Components
 
-| Component      | Destination                                                |
-| -------------- | ---------------------------------------------------------- |
-| `Track`        | `window.dataLayer.push(payload)` (GTM / GA4)               |
-| `TrackShopify` | `window.Shopify.analytics.publish(payload.event, payload)` |
-| `TrackContext` | Provides context inherited by descendant `Track`s          |
+| Component      | Destination                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------- |
+| `Track`        | `window.dataLayer.push(payload)` (GTM / GA4)                                             |
+| `TrackShopify` | `window.Shopify.analytics.publish(payload.event, payload)`, gated on [consent](#consent) |
+| `TrackContext` | Provides context inherited by descendant `Track`s                                        |
 
 `Track` and `TrackShopify` share a common, provider-agnostic base (`AbstractTrack`) and differ only in their [`dispatch()`](#providers) method.
 
@@ -136,7 +136,7 @@ Context is resolved by walking up the ancestor chain (`$closest('TrackContext')`
 `dispatch(payload, event?)` is the seam that sends the resolved payload to its destination:
 
 - **`Track`** — `window.dataLayer.push(payload)`.
-- **`TrackShopify`** — `window.Shopify.analytics.publish(payload.event, payload)`, guarded when the API is unavailable or the payload has no `event` name. Namespace Shopify event names (e.g. `my_app:add_to_cart`).
+- **`TrackShopify`** — `window.Shopify.analytics.publish(payload.event, payload)`, guarded when the API is unavailable, when the payload has no `event` name, and when [analytics consent](#consent) is not granted. Namespace Shopify event names (e.g. `my_app:add_to_cart`).
 
 To send to any other destination (Segment, a custom endpoint, …), extend `Track` and override `dispatch()`:
 
@@ -151,3 +151,28 @@ export class TrackSegment extends Track {
   }
 }
 ```
+
+## Consent
+
+`TrackShopify` is consent-safe by default. Before each publish it calls `window.Shopify.customerPrivacy.analyticsProcessingAllowed()` and publishes only when that call returns `true`.
+
+- The check runs on every dispatch, not once at mount. `window.Shopify` is read fresh each time, so a consent change applies to the next event without a remount.
+- A denied consent drops the event. Nothing is queued, and a dropped event is never replayed once consent is granted.
+- An absent Customer Privacy API drops the event as well. Shopify loads that API asynchronously through `loadFeatures()`, so it is legitimately undefined early in the page's life.
+- Every drop reports a diagnostic, so a missing event is diagnosable instead of silent.
+
+The event name is validated before consent is read. A declaration without an `event` name is wrong for every visitor, so it is reported even when consent is denied.
+
+This gate covers what the platform does not. Shopify's Web Pixels Manager gates App Pixels at load time: it loads a pixel only when the visitor has granted every consent that pixel declares as required. Custom pixels receive every published event and are expected to apply their own consent logic, which is what `TrackShopify` does for you.
+
+`Track` is not gated the same way, on purpose. It appends to `window.dataLayer`, an array in the page that transmits nothing by itself. The tag manager or CMP reading that array decides what leaves the browser, so consent belongs at the tag level there.
+
+## Diagnostics
+
+| Code                                | Reported when                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| `track.invalid-json`                | An attribute value, a `payload` ref or a `context` ref holds malformed JSON   |
+| `track.missing-event-name`          | `TrackShopify` resolved a payload with no string `event` key                  |
+| `track.shopify-unavailable`         | `window.Shopify.analytics.publish` is not a function                          |
+| `track.shopify-privacy-unavailable` | `window.Shopify.customerPrivacy.analyticsProcessingAllowed` is not a function |
+| `track.shopify-consent-denied`      | `analyticsProcessingAllowed()` returned `false`                               |
diff --git a/packages/tests/Track/Track.spec.ts b/packages/tests/Track/Track.spec.ts
index cf524987..24bd7544 100644
--- a/packages/tests/Track/Track.spec.ts
+++ b/packages/tests/Track/Track.spec.ts
@@ -1,11 +1,10 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { getInstance, registerComponents } from '@studiometa/js-toolkit';
 import { captureDiagnostics, mount, resetDom, settle, waitFor } from '@studiometa/js-toolkit/test';
 import { Track } from '#private/Track/Track.js';
 import { TrackContext } from '#private/Track/TrackContext.js';
-import { TrackShopify } from '#private/Track/TrackShopify.js';
 
-registerComponents(Track, TrackContext, TrackShopify);
+registerComponents(Track, TrackContext);
 
 /**
  * Record diagnostics and cancel their default sink.
@@ -629,53 +628,3 @@ describe('the intersection service under load', () => {
     expect(pushes()).toHaveLength(CARDS);
   });
 });
-
-describe('TrackShopify — the dispatch seam', () => {
-  it('publishes through window.Shopify.analytics.publish', async () => {
-    const publish = vi.fn();
-    window.Shopify = { analytics: { publish } };
-
-    const root = await mount(`
-      <div data-component="TrackContext" data-option-context='{"page_type": "product"}'>
-        <button data-component="TrackShopify" data-track:click='{"event": "add_to_cart", "id": "1"}'></button>
-      </div>
-    `);
-    root.querySelector('button')?.click();
-
-    expect(publish).toHaveBeenCalledTimes(1);
-    expect(publish).toHaveBeenCalledWith('add_to_cart', {
-      page_type: 'product',
-      event: 'add_to_cart',
-      id: '1',
-    });
-    expect(pushes()).toHaveLength(0);
-    delete window.Shopify;
-  });
-
-  it('publishes nothing without a string `event` name', async () => {
-    const publish = vi.fn();
-    window.Shopify = { analytics: { publish } };
-    const log = captureDiagnostics();
-
-    const root = await mount(
-      `<button data-component="TrackShopify" data-track:click='{"id": "1"}'></button>`,
-    );
-    root.querySelector('button')?.click();
-
-    expect(publish).not.toHaveBeenCalled();
-    expect(log.codes).toContain('track.missing-event-name');
-    log.stop();
-    delete window.Shopify;
-  });
-
-  it('does not throw when the Shopify analytics API is absent', async () => {
-    const log = captureDiagnostics();
-    const root = await mount(
-      `<button data-component="TrackShopify" data-track:click='{"event": "x"}'></button>`,
-    );
-
-    expect(() => root.querySelector('button')?.click()).not.toThrow();
-    expect(log.codes).toContain('track.shopify-unavailable');
-    log.stop();
-  });
-});
diff --git a/packages/tests/Track/TrackShopify.spec.ts b/packages/tests/Track/TrackShopify.spec.ts
new file mode 100644
index 00000000..08765e13
--- /dev/null
+++ b/packages/tests/Track/TrackShopify.spec.ts
@@ -0,0 +1,254 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { registerComponents } from '@studiometa/js-toolkit';
+import { captureDiagnostics, mount, resetDom } from '@studiometa/js-toolkit/test';
+import { TrackContext } from '#private/Track/TrackContext.js';
+import { TrackShopify } from '#private/Track/TrackShopify.js';
+
+registerComponents(TrackContext, TrackShopify);
+
+/** The spy standing in for `window.Shopify.analytics.publish`. */
+let publish: ReturnType<typeof vi.fn>;
+
+/**
+ * Install a Shopify global.
+ *
+ * `allowed` is the `analyticsProcessingAllowed` implementation. The component
+ * calls it on every dispatch, so a test can flip consent between two events
+ * the way a consent banner does. Omit it to leave the Customer Privacy API
+ * absent, which is the state of a page whose `loadFeatures()` has not resolved.
+ */
+function stubShopify({ allowed }: { allowed?: () => boolean } = {}): void {
+  window.Shopify = {
+    analytics: { publish },
+    ...(allowed ? { customerPrivacy: { analyticsProcessingAllowed: allowed } } : {}),
+  };
+}
+
+beforeEach(() => {
+  publish = vi.fn();
+});
+
+afterEach(async () => {
+  delete window.Shopify;
+  await resetDom();
+});
+
+describe('TrackShopify — consent', () => {
+  it('publishes when analytics processing is allowed', async () => {
+    stubShopify({ allowed: () => true });
+
+    const root = await mount(`
+      <div data-component="TrackContext" data-option-context='{"page_type": "product"}'>
+        <button data-component="TrackShopify" data-track:click='{"event": "add_to_cart", "id": "1"}'></button>
+      </div>
+    `);
+    root.querySelector('button')?.click();
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(publish).toHaveBeenCalledWith('add_to_cart', {
+      page_type: 'product',
+      event: 'add_to_cart',
+      id: '1',
+    });
+  });
+
+  it('publishes nothing when analytics processing is denied', async () => {
+    stubShopify({ allowed: () => false });
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).not.toHaveBeenCalled();
+    expect(log.codes).toContain('track.shopify-consent-denied');
+    log.stop();
+  });
+
+  it('publishes nothing when the customer privacy API is absent', async () => {
+    stubShopify();
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).not.toHaveBeenCalled();
+    expect(log.codes).toContain('track.shopify-privacy-unavailable');
+    log.stop();
+  });
+
+  it('publishes nothing when the customer privacy API carries no `analyticsProcessingAllowed`', async () => {
+    window.Shopify = { analytics: { publish }, customerPrivacy: {} };
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).not.toHaveBeenCalled();
+    expect(log.codes).toContain('track.shopify-privacy-unavailable');
+    log.stop();
+  });
+
+  it('follows a consent change without a remount', async () => {
+    let allowed = false;
+    stubShopify({ allowed: () => allowed });
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    const button = root.querySelector('button') as HTMLButtonElement;
+
+    button.click();
+    expect(publish).not.toHaveBeenCalled();
+
+    allowed = true;
+    button.click();
+    expect(publish).toHaveBeenCalledTimes(1);
+
+    allowed = false;
+    button.click();
+    expect(publish).toHaveBeenCalledTimes(1);
+
+    log.stop();
+  });
+
+  it('sees a customer privacy API that appears after mount', async () => {
+    stubShopify();
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    const button = root.querySelector('button') as HTMLButtonElement;
+
+    button.click();
+    expect(publish).not.toHaveBeenCalled();
+
+    // What `loadFeatures()` does once the Customer Privacy API has loaded.
+    window.Shopify!.customerPrivacy = { analyticsProcessingAllowed: () => true };
+    button.click();
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    log.stop();
+  });
+
+  it('does not replay an event dropped before consent was granted', async () => {
+    let allowed = false;
+    stubShopify({ allowed: () => allowed });
+    const log = captureDiagnostics();
+
+    const root = await mount(`
+      <button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>
+      <button data-component="TrackShopify" data-track:click='{"event": "begin_checkout"}'></button>
+    `);
+    const [dropped, sent] = Array.from(root.querySelectorAll('button'));
+
+    dropped.click();
+    allowed = true;
+    sent.click();
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(publish).toHaveBeenCalledWith('begin_checkout', { event: 'begin_checkout' });
+    log.stop();
+  });
+
+  it('adds no customer identifier to the published payload', async () => {
+    stubShopify({ allowed: () => true });
+
+    const root = await mount(`
+      <div data-component="TrackContext" data-option-context='{"page_type": "product"}'>
+        <button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>
+      </div>
+    `);
+    root.querySelector('button')?.click();
+
+    const [name, payload] = publish.mock.calls[0] as [string, Record<string, unknown>];
+    expect(name).toBe('add_to_cart');
+    // An exact match: the payload holds the declared layers and nothing else.
+    expect(payload).toEqual({ page_type: 'product', event: 'add_to_cart' });
+  });
+});
+
+describe('TrackShopify — the dispatch seam', () => {
+  it('publishes nothing and does not throw when the analytics API is absent', async () => {
+    const log = captureDiagnostics();
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "x"}'></button>`,
+    );
+
+    expect(() => root.querySelector('button')?.click()).not.toThrow();
+    expect(log.codes).toContain('track.shopify-unavailable');
+    log.stop();
+  });
+
+  it('publishes nothing without a string `event` name', async () => {
+    stubShopify({ allowed: () => true });
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"id": "1"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).not.toHaveBeenCalled();
+    expect(log.codes).toContain('track.missing-event-name');
+    log.stop();
+  });
+
+  it('reports a missing `event` name even while consent is denied', async () => {
+    stubShopify({ allowed: () => false });
+    const log = captureDiagnostics();
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"id": "1"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).not.toHaveBeenCalled();
+    // The declaration is broken for every visitor, so it is reported before
+    // the consent drop instead of being masked by it.
+    expect(log.codes).toContain('track.missing-event-name');
+    expect(log.codes).not.toContain('track.shopify-consent-denied');
+    log.stop();
+  });
+
+  it('keeps `this` bound to window.Shopify.analytics when publishing', async () => {
+    let receiver: unknown;
+    window.Shopify = {
+      analytics: {
+        publish(...args: [string, Record<string, unknown>]) {
+          receiver = this;
+          publish(...args);
+        },
+      },
+      customerPrivacy: { analyticsProcessingAllowed: () => true },
+    };
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(receiver).toBe(window.Shopify?.analytics);
+  });
+
+  it('never touches window.dataLayer', async () => {
+    stubShopify({ allowed: () => true });
+    window.dataLayer = [];
+
+    const root = await mount(
+      `<button data-component="TrackShopify" data-track:click='{"event": "add_to_cart"}'></button>`,
+    );
+    root.querySelector('button')?.click();
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(window.dataLayer).toHaveLength(0);
+  });
+});
diff --git a/packages/ui/src/Track/TrackShopify.ts b/packages/ui/src/Track/TrackShopify.ts
index 1e2b3da6..8d9e48e8 100644
--- a/packages/ui/src/Track/TrackShopify.ts
+++ b/packages/ui/src/Track/TrackShopify.ts
@@ -7,19 +7,38 @@ declare global {
       analytics?: {
         publish?: (event: string, payload: Record<string, unknown>) => void;
       };
+      customerPrivacy?: {
+        analyticsProcessingAllowed?: () => boolean;
+      };
     };
   }
 }
 
 export type TrackShopifyProps = AbstractTrackProps;
 
-/** Publishes tracking payloads through `window.Shopify.analytics.publish`. */
+/**
+ * Publishes tracking payloads through `window.Shopify.analytics.publish`.
+ *
+ * Shopify's Web Pixels Manager gates App Pixels at load time, but it hands
+ * every published event to custom pixels, which are expected to apply their
+ * own consent logic. This component publishes only when
+ * `window.Shopify.customerPrivacy.analyticsProcessingAllowed()` returns
+ * `true`, so a storefront does not repeat that check before each event.
+ *
+ * @example
+ * ```html
+ * <button data-component="TrackShopify" data-track:click='{"event": "my_app:add_to_cart"}'>Add to cart</button>
+ * ```
+ */
 export class TrackShopify<T extends BaseProps = BaseProps> extends AbstractTrack<T> {
   static config: BaseConfig = {
     name: 'TrackShopify',
   };
 
   dispatch(payload: Record<string, unknown>): void {
+    // Read fresh on every dispatch. The Customer Privacy API is loaded
+    // asynchronously through `loadFeatures()` and the visitor can change their
+    // choice at any time, so anything resolved at mount would go stale.
     const analytics = window.Shopify?.analytics;
 
     if (typeof analytics?.publish !== 'function') {
@@ -38,6 +57,29 @@ export class TrackShopify<T extends BaseProps = BaseProps> extends AbstractTrack
       return;
     }
 
+    // Consent is checked last on purpose. The two checks above catch a broken
+    // environment and a broken declaration, which are wrong for every visitor,
+    // while a consent drop follows one visitor's choice. Checking consent first
+    // would hide an authoring mistake behind a legitimate drop.
+    const customerPrivacy = window.Shopify?.customerPrivacy;
+
+    if (typeof customerPrivacy?.analyticsProcessingAllowed !== 'function') {
+      this.$warn(
+        'track.shopify-privacy-unavailable',
+        '`window.Shopify.customerPrivacy.analyticsProcessingAllowed` is not available, the event is dropped.',
+      );
+      return;
+    }
+
+    // Called as a method so `this` stays bound to `window.Shopify.customerPrivacy`.
+    if (!customerPrivacy.analyticsProcessingAllowed()) {
+      this.$warn(
+        'track.shopify-consent-denied',
+        'Analytics processing is not allowed, the event is dropped.',
+      );
+      return;
+    }
+
     // Called as a method so `this` stays bound to `window.Shopify.analytics`.
     analytics.publish(payload.event, payload);
   }