Web Pixel 扩展

Web Pixel 扩展是 Shopify 以隐私优先的方式实现客户事件追踪和分析。它们不会向店面注入任意 JavaScript（这可能导致性能下降和隐私违规），而是在沙箱化环境中运行，对客户数据具有受控的访问权限。它们接收标准化的电子商务事件，并可以在尊重客户同意偏好的同时将数据转发到分析平台。

为什么使用 Web Pixel？

传统的追踪脚本（Google Tag Manager、Facebook Pixel 等）拥有完整的页面访问权限，可能会拖慢店面速度，并且经常在没有适当同意的情况下收集数据。Shopify 的 Web Pixel 框架解决了这三个问题：沙箱化执行以保障性能、标准化事件以确保一致性，以及内置同意管理以实现隐私合规。

Web Pixel 的工作原理

Web Pixel 在沙箱化的 Web Worker 中运行。它们无法访问 DOM、读取 Cookie 或直接与页面交互。相反，它们订阅 Shopify 在客户浏览、添加商品到购物车和完成购买时发出的标准化客户事件流。

客户事件

Shopify 发出一套全面的标准化电子商务事件。你的 Pixel 订阅所需的事件：

Event	Trigger	Key Data
`page_viewed`	Customer views any page	URL, page title, referrer
`product_viewed`	Customer views a product page	Product ID, title, price, variant
`collection_viewed`	Customer views a collection	Collection ID, title
`search_submitted`	Customer performs a search	Search query, result count
`product_added_to_cart`	Item added to cart	Product, variant, quantity, cart total
`product_removed_from_cart`	Item removed from cart	Product, variant, quantity
`cart_viewed`	Customer views the cart page	Cart contents, total
`checkout_started`	Customer begins checkout	Cart contents, total, discount codes
`checkout_address_info_submitted`	Address form completed	Country, province (no PII)
`checkout_shipping_info_submitted`	Shipping method selected	Shipping method, cost
`payment_info_submitted`	Payment details entered	Payment method type (no card details)
`checkout_completed`	Purchase completed	Order ID, total, line items, currency

事件数据隐私

客户事件默认包含匿名化数据。个人身份信息（PII），如电子邮件地址和全名，仅在客户明确授予同意时才会包含。你的 Pixel 必须在访问 PII 字段之前检查 event.data.customer.consent。

创建 Web Pixel 扩展

# Generate a web pixel extension
shopify app generate extension --template web_pixel --name custom-analytics

extensions/custom-analytics/
├── src/
│   └── index.ts
├── shopify.extension.toml
└── package.json

Extension Configuration

# extensions/custom-analytics/shopify.extension.toml
api_version = "2025-01"

[[extensions]]
type = "web_pixel_extension"
name = "Custom Analytics Pixel"
handle = "custom-analytics"

[extensions.settings]
  [[extensions.settings.fields]]
  key = "analytics_endpoint"
  type = "single_line_text_field"
  name = "Analytics Endpoint URL"
  description = "The URL where event data will be sent"

  [[extensions.settings.fields]]
  key = "api_key"
  type = "single_line_text_field"
  name = "API Key"
  description = "Your analytics platform API key"

  [[extensions.settings.fields]]
  key = "track_search"
  type = "boolean"
  name = "Track Search Events"
  description = "Enable tracking of search queries"

自定义像素实现

Pixel 入口点订阅事件并处理它们。以下是一个追踪关键电子商务事件的完整实现：

// extensions/custom-analytics/src/index.ts
import { register } from '@shopify/web-pixels-extension';

register(({ analytics, browser, settings, init }) => {
  const endpoint = settings.analytics_endpoint;
  const apiKey = settings.api_key;
  const trackSearch = settings.track_search === 'true';

  // Helper to send events to your analytics backend
  async function sendEvent(eventName: string, payload: Record<string, any>) {
    try {
      await fetch(endpoint, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': apiKey,
        },
        body: JSON.stringify({
          event: eventName,
          timestamp: new Date().toISOString(),
          shopId: init.data.shop.id,
          payload,
        }),
        // Use keepalive to ensure the request completes
        // even if the customer navigates away
        keepalive: true,
      });
    } catch (err) {
      // Silently fail -- do not disrupt the customer experience
      console.error(`Failed to send ${eventName} event:`, err);
    }
  }

  // Track page views
  analytics.subscribe('page_viewed', (event) => {
    sendEvent('page_view', {
      url: event.data.url,
      title: event.data.pageTitle,
      referrer: event.data.referrer,
    });
  });

  // Track product views
  analytics.subscribe('product_viewed', (event) => {
    const product = event.data.productVariant;
    sendEvent('product_view', {
      productId: product?.product?.id,
      productTitle: product?.product?.title,
      variantId: product?.id,
      variantTitle: product?.title,
      price: product?.price?.amount,
      currency: product?.price?.currencyCode,
    });
  });

  // Track add to cart
  analytics.subscribe('product_added_to_cart', (event) => {
    const cartLine = event.data.cartLine;
    sendEvent('add_to_cart', {
      productId: cartLine?.merchandise?.product?.id,
      productTitle: cartLine?.merchandise?.product?.title,
      variantId: cartLine?.merchandise?.id,
      quantity: cartLine?.quantity,
      price: cartLine?.merchandise?.price?.amount,
      currency: cartLine?.merchandise?.price?.currencyCode,
    });
  });

  // Track cart removals
  analytics.subscribe('product_removed_from_cart', (event) => {
    const cartLine = event.data.cartLine;
    sendEvent('remove_from_cart', {
      productId: cartLine?.merchandise?.product?.id,
      variantId: cartLine?.merchandise?.id,
      quantity: cartLine?.quantity,
    });
  });

  // Track checkout started
  analytics.subscribe('checkout_started', (event) => {
    const checkout = event.data.checkout;
    sendEvent('begin_checkout', {
      totalPrice: checkout?.totalPrice?.amount,
      currency: checkout?.totalPrice?.currencyCode,
      lineItemCount: checkout?.lineItems?.length,
      discountCodes: checkout?.discountApplications?.map(
        (d: any) => d.title
      ),
    });
  });

  // Track purchase completed
  analytics.subscribe('checkout_completed', (event) => {
    const checkout = event.data.checkout;
    sendEvent('purchase', {
      orderId: checkout?.order?.id,
      totalPrice: checkout?.totalPrice?.amount,
      subtotalPrice: checkout?.subtotalPrice?.amount,
      totalTax: checkout?.totalTax?.amount,
      currency: checkout?.totalPrice?.currencyCode,
      lineItems: checkout?.lineItems?.map((item: any) => ({
        productId: item.variant?.product?.id,
        productTitle: item.variant?.product?.title,
        variantId: item.variant?.id,
        quantity: item.quantity,
        price: item.variant?.price?.amount,
      })),
      shippingRate: {
        price: checkout?.shippingLine?.price?.amount,
      },
    });
  });

  // Conditionally track search
  if (trackSearch) {
    analytics.subscribe('search_submitted', (event) => {
      sendEvent('search', {
        query: event.data.searchResult?.query,
        resultCount: event.data.searchResult?.productVariants?.length ?? 0,
      });
    });
  }

  // Track collection views
  analytics.subscribe('collection_viewed', (event) => {
    sendEvent('collection_view', {
      collectionId: event.data.collection?.id,
      collectionTitle: event.data.collection?.title,
    });
  });
});

隐私合规分析

Shopify 的 Web Pixel 框架与客户隐私同意系统集成。你的 Pixel 必须遵守同意状态。

同意感知的事件处理

// Enhanced pixel with consent checking
register(({ analytics, browser, settings, init }) => {
  const endpoint = settings.analytics_endpoint;

  // Check initial consent status
  let analyticsConsent = init.customerPrivacy?.analyticsProcessingAllowed ?? false;
  let marketingConsent = init.customerPrivacy?.marketingAllowed ?? false;

  // Listen for consent changes (customer updates preferences)
  analytics.subscribe('visitor_consent_collected', (event) => {
    analyticsConsent = event.data.analyticsAllowed;
    marketingConsent = event.data.marketingAllowed;
  });

  async function sendEvent(
    eventName: string,
    payload: Record<string, any>,
    requiresMarketingConsent: boolean = false
  ) {
    // Always check consent before sending data
    if (!analyticsConsent) return;
    if (requiresMarketingConsent && !marketingConsent) return;

    await fetch(endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event: eventName,
        timestamp: new Date().toISOString(),
        consent: {
          analytics: analyticsConsent,
          marketing: marketingConsent,
        },
        payload,
      }),
      keepalive: true,
    });
  }

  // Basic analytics events (require analytics consent)
  analytics.subscribe('page_viewed', (event) => {
    sendEvent('page_view', {
      url: event.data.url,
      title: event.data.pageTitle,
    });
  });

  // Marketing-related events (require marketing consent)
  analytics.subscribe('checkout_completed', (event) => {
    // Send conversion data to ad platforms only with marketing consent
    sendEvent(
      'conversion',
      {
        orderId: event.data.checkout?.order?.id,
        value: event.data.checkout?.totalPrice?.amount,
        currency: event.data.checkout?.totalPrice?.currencyCode,
      },
      true // requires marketing consent
    );
  });
});

GDPR 和隐私法规

你的 Web Pixel 必须符合 GDPR、CCPA 和其他隐私法规。关键要求：

不要在未经同意的情况下收集 PII -- 即使事件数据中包含它
尊重退出请求 -- 当客户撤回同意时，立即停止发送数据
数据最小化 -- 只收集你需要的内容。不要将原始事件负载转发给第三方
保留限制 -- 确保你的分析后端按照你的隐私政策时间线删除数据

违规可能导致你的应用从 Shopify App Store 移除以及潜在的法律责任。

与第三方分析集成

Google Analytics 4

// GA4 integration via Measurement Protocol
register(({ analytics, settings }) => {
  const measurementId = settings.ga4_measurement_id;
  const apiSecret = settings.ga4_api_secret;
  const GA4_ENDPOINT = `https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`;

  function sendToGA4(eventName: string, params: Record<string, any>) {
    fetch(GA4_ENDPOINT, {
      method: 'POST',
      body: JSON.stringify({
        client_id: generateClientId(), // Generate a privacy-safe client ID
        events: [{ name: eventName, params }],
      }),
      keepalive: true,
    });
  }

  analytics.subscribe('product_viewed', (event) => {
    const product = event.data.productVariant;
    sendToGA4('view_item', {
      currency: product?.price?.currencyCode,
      value: parseFloat(product?.price?.amount || '0'),
      items: [{
        item_id: product?.product?.id,
        item_name: product?.product?.title,
        item_variant: product?.title,
        price: parseFloat(product?.price?.amount || '0'),
      }],
    });
  });

  analytics.subscribe('product_added_to_cart', (event) => {
    const cartLine = event.data.cartLine;
    sendToGA4('add_to_cart', {
      currency: cartLine?.merchandise?.price?.currencyCode,
      value: parseFloat(cartLine?.merchandise?.price?.amount || '0') * (cartLine?.quantity || 1),
      items: [{
        item_id: cartLine?.merchandise?.product?.id,
        item_name: cartLine?.merchandise?.product?.title,
        quantity: cartLine?.quantity,
        price: parseFloat(cartLine?.merchandise?.price?.amount || '0'),
      }],
    });
  });

  analytics.subscribe('checkout_completed', (event) => {
    const checkout = event.data.checkout;
    sendToGA4('purchase', {
      transaction_id: checkout?.order?.id,
      currency: checkout?.totalPrice?.currencyCode,
      value: parseFloat(checkout?.totalPrice?.amount || '0'),
      tax: parseFloat(checkout?.totalTax?.amount || '0'),
      shipping: parseFloat(checkout?.shippingLine?.price?.amount || '0'),
      items: checkout?.lineItems?.map((item: any) => ({
        item_id: item.variant?.product?.id,
        item_name: item.variant?.product?.title,
        quantity: item.quantity,
        price: parseFloat(item.variant?.price?.amount || '0'),
      })),
    });
  });
});

function generateClientId(): string {
  // Generate a random client ID that does not contain PII
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(
    /[xy]/g,
    (c) => {
      const r = (Math.random() * 16) | 0;
      const v = c === 'x' ? r : (r & 0x3) | 0x8;
      return v.toString(16);
    }
  );
}

Meta Conversions API

// Meta (Facebook) Conversions API integration
register(({ analytics, settings }) => {
  const pixelId = settings.meta_pixel_id;
  const accessToken = settings.meta_access_token;
  const META_ENDPOINT = `https://graph.facebook.com/v18.0/${pixelId}/events`;

  function sendToMeta(eventName: string, customData: Record<string, any>) {
    fetch(META_ENDPOINT, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        data: [{
          event_name: eventName,
          event_time: Math.floor(Date.now() / 1000),
          action_source: 'website',
          custom_data: customData,
        }],
        access_token: accessToken,
      }),
      keepalive: true,
    });
  }

  analytics.subscribe('product_viewed', (event) => {
    const product = event.data.productVariant;
    sendToMeta('ViewContent', {
      content_ids: [product?.product?.id],
      content_type: 'product',
      content_name: product?.product?.title,
      value: parseFloat(product?.price?.amount || '0'),
      currency: product?.price?.currencyCode,
    });
  });

  analytics.subscribe('product_added_to_cart', (event) => {
    const cartLine = event.data.cartLine;
    sendToMeta('AddToCart', {
      content_ids: [cartLine?.merchandise?.product?.id],
      content_type: 'product',
      value: parseFloat(cartLine?.merchandise?.price?.amount || '0'),
      currency: cartLine?.merchandise?.price?.currencyCode,
    });
  });

  analytics.subscribe('checkout_completed', (event) => {
    const checkout = event.data.checkout;
    sendToMeta('Purchase', {
      content_ids: checkout?.lineItems?.map(
        (item: any) => item.variant?.product?.id
      ),
      content_type: 'product',
      value: parseFloat(checkout?.totalPrice?.amount || '0'),
      currency: checkout?.totalPrice?.currencyCode,
      num_items: checkout?.lineItems?.length,
    });
  });
});

测试和调试

# Start development server with pixel debugging
shopify app dev

# The CLI provides a preview URL with pixel debugging enabled
# Open the browser console to see pixel event logs

调试模式

register(({ analytics, settings, init }) => {
  const debug = init.data.shop.myshopifyDomain.includes('dev');

  function log(eventName: string, data: any) {
    if (debug) {
      console.log(`[Pixel Debug] ${eventName}:`, JSON.stringify(data, null, 2));
    }
  }

  analytics.subscribe('page_viewed', (event) => {
    log('page_viewed', event.data);
    // ... normal processing
  });
});

在开发环境中测试 Pixel

使用浏览器的 Network 标签验证你的 Pixel 是否正在向正确的端点发送请求。Shopify 的开发工具还提供了一个"Customer Events"调试器，显示页面上发出的每个事件以及哪些 Pixel 接收了它。通过在开发商店上使用 ?debug_pixels=true 查询参数访问。

性能注意事项

在所有 fetch 请求上使用 keepalive: true -- 这确保即使客户在请求过程中导航离开，事件也会被发送
尽可能批量处理事件 -- 不要每个事件发送一个请求，而是缓冲事件并每隔几秒批量发送
最小化负载大小 -- 只包含你的分析平台需要的数据
避免同步模式 -- Pixel 中的所有内容都应该是非阻塞的
静默处理网络故障 -- 永远不要让追踪故障影响客户体验

// Event batching implementation
class EventBatcher {
  private queue: any[] = [];
  private timer: ReturnType<typeof setTimeout> | null = null;
  private readonly endpoint: string;
  private readonly batchSize: number;
  private readonly flushInterval: number;

  constructor(endpoint: string, batchSize = 10, flushInterval = 3000) {
    this.endpoint = endpoint;
    this.batchSize = batchSize;
    this.flushInterval = flushInterval;
  }

  add(event: any) {
    this.queue.push(event);

    if (this.queue.length >= this.batchSize) {
      this.flush();
    } else if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), this.flushInterval);
    }
  }

  private flush() {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }

    if (this.queue.length === 0) return;

    const batch = this.queue.splice(0, this.batchSize);

    fetch(this.endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ events: batch }),
      keepalive: true,
    }).catch(() => {
      // Re-queue failed events (with a retry limit)
      // In production, add exponential backoff
    });
  }
}

总结

Web Pixel 扩展提供了一种安全、高性能且隐私合规的方式来追踪 Shopify 店面上的客户行为。通过使用 Shopify 的标准化事件系统，你可以在所有商家中获得一致的数据，而无需脆弱的 DOM 抓取或 Cookie 追踪。结合同意管理，你的分析集成已为隐私优先的网络做好准备。

Web Pixel 的工作原理​

客户事件​

创建 Web Pixel 扩展​

Extension Configuration​

自定义像素实现​

隐私合规分析​

同意感知的事件处理​

与第三方分析集成​

Google Analytics 4​

Meta Conversions API​

测试和调试​

调试模式​

性能注意事项​