analytics-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analytics Integration

分析工具集成

Overview

概述

Implement a robust analytics stack for e-commerce using Google Analytics 4 (GA4), Meta Pixel, and Google Tag Manager (GTM). Covers structured data layer design for product and checkout events, server-side tagging via GTM server containers to improve data accuracy and bypass browser restrictions, and Meta Conversions API for reliable ad attribution.

为电商平台搭建一套基于Google Analytics 4 (GA4)、Meta Pixel和Google Tag Manager (GTM)的可靠分析栈。内容涵盖产品与结账事件的结构化数据层设计、通过GTM服务器容器实现服务器端标签配置以提升数据准确性并绕过浏览器限制，以及用于可靠广告归因的Meta Conversions API。

When to Use This Skill

适用场景

When adding GA4 e-commerce tracking (product views, add-to-cart, checkout steps, purchase) to a new or existing store
When implementing Meta Pixel alongside the Conversions API for dual-mode event delivery to improve ad attribution
When migrating a GTM web container to a server-side container for better data control and cookie lifespans
When troubleshooting missing or duplicate conversion events caused by ad blockers or client-side failures
When meeting privacy requirements that mandate server-side deduplication between browser and server events

为新上线或已有的店铺添加GA4电商跟踪（商品浏览、加入购物车、结账步骤、购买）功能时
同时部署Meta Pixel与Conversions API，采用双模式事件传递以提升广告归因效果时
将GTM网页容器迁移至服务器端容器，以获得更好的数据控制权和Cookie有效期时
排查因广告拦截器或客户端故障导致的转化事件缺失或重复问题时
满足隐私要求，需要在浏览器与服务器事件之间进行服务器端去重时

Core Instructions

核心操作指南

Step 1: Determine your platform and recommended approach

步骤1：确定平台与推荐方案

Platform	Recommended Analytics Setup	Key Actions
Shopify	Built-in GA4 integration + GTM app	Connect GA4 in Online Store → Preferences → Google Analytics; install GTM4WP or the official Google & YouTube channel app for Meta Pixel
WooCommerce	MonsterInsights plugin for GA4 + GTM	Install MonsterInsights (free tier or Pro from $99/yr) for GA4; install WooCommerce Google Analytics Integration (free) for enhanced e-commerce events
BigCommerce	Native GA4 integration + channel manager	Connect GA4 in Advanced Settings → Data Solutions → Google Analytics; use BigCommerce's Meta Pixel integration under the Channel Manager
Custom / Headless	GTM container + server-side container + custom data layer	Implement a canonical data layer, deploy GTM server container on Cloud Run or Vercel, and add Meta Conversions API from your backend

平台	推荐分析配置	关键操作
Shopify	内置GA4集成 + GTM应用	在在线商店 → 偏好设置 → Google Analytics中连接GA4；安装GTM4WP或官方Google & YouTube渠道应用以配置Meta Pixel
WooCommerce	MonsterInsights插件（用于GA4） + GTM	从wordpress.org安装MonsterInsights（免费版可用，专业版起价99美元/年）以配置GA4；安装免费的WooCommerce Google Analytics Integration以获取增强型电商事件
BigCommerce	原生GA4集成 + 渠道管理器	在高级设置 → 数据解决方案 → Google Analytics中连接GA4；在渠道管理器下使用BigCommerce的Meta Pixel集成
自定义/无头电商	GTM容器 + 服务器端容器 + 自定义数据层	实现标准数据层，在Cloud Run或Vercel上部署GTM服务器容器，并从后端添加Meta Conversions API

Step 2: Platform-specific analytics setup

步骤2：平台专属分析配置

Shopify

Connect GA4 (built-in, no code required):

Go to Online Store → Preferences → Google Analytics
Click Connect your Google account and select your GA4 property
Shopify sends all standard e-commerce events automatically:
```
page_view
```
,
```
view_item
```
,
```
add_to_cart
```
,
```
begin_checkout
```
,
```
purchase
```
In Google Analytics → Configure → Events, mark the
```
purchase
```
event as a conversion

Track checkout funnel with GA4 Explorations:

In GA4, go to Explore → Funnel exploration
Create funnel steps:
- Step 1:
```
begin_checkout
```
  event
- Step 2:
```
add_shipping_info
```
  event
- Step 3:
```
add_payment_info
```
  event
- Step 4:
```
purchase
```
  event
This shows exactly where shoppers drop off in checkout

Add Meta Pixel:

Go to the Shopify App Store and install the Meta channel app (free)
Follow the setup wizard to connect your Facebook Business account
Meta sends pixel events automatically through the Shopify integration, including the Conversions API for server-side deduplication

连接GA4（内置无代码配置）：

进入在线商店 → 偏好设置 → Google Analytics
点击连接你的Google账户并选择GA4媒体资源
Shopify会自动发送所有标准电商事件：
```
page_view
```
、
```
view_item
```
、
```
add_to_cart
```
、
```
begin_checkout
```
、
```
purchase
```
在Google Analytics → 配置 → 事件中，将
```
purchase
```
事件标记为转化事件

使用GA4探索功能跟踪结账漏斗：

在GA4中，进入探索 → 漏斗探索
创建漏斗步骤：
- 步骤1：
```
begin_checkout
```
  事件
- 步骤2：
```
add_shipping_info
```
  事件
- 步骤3：
```
add_payment_info
```
  事件
- 步骤4：
```
purchase
```
  事件
该漏斗将清晰展示购物者在结账流程中的流失节点

添加Meta Pixel：

前往Shopify应用商店并安装免费的Meta渠道应用
按照设置向导连接你的Facebook商务账户
Meta会通过Shopify集成自动发送像素事件，包括用于服务器端去重的Conversions API

WooCommerce

Install MonsterInsights for GA4:

Install MonsterInsights from wordpress.org (free tier available; Pro from $99/year adds enhanced e-commerce)
Go to Insights → Settings → General and connect your GA4 property
Enable Enhanced eCommerce Tracking in the MonsterInsights settings — this sends
```
add_to_cart
```
,
```
begin_checkout
```
, and
```
purchase
```
events to GA4 with product-level data

Add Meta Pixel:

Install PixelYourSite (free tier available, pro from $69/year) from wordpress.org
Enter your Pixel ID and connect via Facebook's Business Integration
PixelYourSite includes the WooCommerce extension for
```
ViewContent
```
,
```
AddToCart
```
,
```
InitiateCheckout
```
, and
```
Purchase
```
events

Verify events are firing:

Install the Meta Pixel Helper Chrome extension
Visit your product page and checkout — the extension shows which events fire on each page
In GA4, use Admin → DebugView to confirm events arrive in real time

安装MonsterInsights以配置GA4：

从wordpress.org安装MonsterInsights（免费版可用；专业版起价99美元/年，支持增强型电商功能）
进入Insights → 设置 → 常规并连接GA4媒体资源
在MonsterInsights设置中启用增强型电商跟踪——这会将
```
add_to_cart
```
、
```
begin_checkout
```
和
```
purchase
```
事件连同商品级数据发送至GA4

添加Meta Pixel：

从wordpress.org安装PixelYourSite（免费版可用，专业版起价69美元/年）
输入你的Pixel ID并通过Facebook商务集成完成连接
PixelYourSite包含WooCommerce扩展，支持
```
ViewContent
```
、
```
AddToCart
```
、
```
InitiateCheckout
```
和
```
Purchase
```
事件

验证事件触发情况：

安装Chrome扩展Meta Pixel Helper
访问商品页面和结账流程——该扩展会显示每个页面触发的事件
在GA4中，使用管理 → 调试视图实时确认事件是否送达

BigCommerce

Connect GA4 (built-in):

Go to Advanced Settings → Data Solutions → Google Analytics
Enter your GA4 Measurement ID (format:
```
G-XXXXXXXX
```
)
BigCommerce fires e-commerce events automatically including
```
purchase
```
with full order data

Add Meta Pixel:

Go to Channel Manager → Marketplace → Meta
Connect your Facebook Business account
BigCommerce sends Pixel events natively and supports the Conversions API for server-side deduplication

连接GA4（内置配置）：

进入高级设置 → 数据解决方案 → Google Analytics
输入GA4测量ID（格式：
```
G-XXXXXXXX
```
）
BigCommerce会自动触发电商事件，包括带有完整订单数据的
```
purchase
```
事件

添加Meta Pixel：

进入渠道管理器 → 应用市场 → Meta
连接你的Facebook商务账户
BigCommerce原生支持发送Pixel事件，并兼容Conversions API以实现服务器端去重

Custom / Headless

自定义/无头电商

Design a canonical data layer first — every event follows the same shape regardless of which vendor consumes it:

javascript

// dataLayer must be initialized in <head> before GTM loads
window.dataLayer = window.dataLayer || [];

// Always clear ecommerce before pushing a new event (prevents GTM from merging stale items)
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'USD',
    value: product.price * quantity,
    items: [{
      item_id: product.sku,
      item_name: product.name,
      item_brand: product.brand,
      item_category: product.category,
      price: product.price,
      quantity,
    }],
  },
});

Purchase event (fire after order confirmed, use server-generated order ID as
transaction_id
):

javascript

window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: order.id,  // Must be unique — deduplicate browser + server events
    value: order.total,
    tax: order.tax,
    shipping: order.shippingCost,
    currency: order.currency,
    coupon: order.couponCode || '',
    items: order.lineItems.map(line => ({
      item_id: line.sku,
      item_name: line.name,
      price: line.unitPrice,
      quantity: line.qty,
    })),
  },
});

Meta Pixel with Conversions API deduplication — send the same event from browser and server using a shared

event_id

javascript

// Browser — pass event_id for deduplication
const eventId = `purchase_${order.id}`;
fbq('track', 'Purchase', {
  value: order.total,
  currency: order.currency,
  content_ids: order.lineItems.map(l => l.sku),
  content_type: 'product',
}, { eventID: eventId });

// Send eventId to server for the Conversions API mirror
await fetch('/api/analytics/meta-purchase', {
  method: 'POST',
  body: JSON.stringify({ orderId: order.id, eventId }),
});

javascript

// Server-side Conversions API (Node.js)
import { ServerEvent, EventRequest, UserData, CustomData } from 'facebook-nodejs-business-sdk';

export async function sendMetaPurchase(order, eventId, userAgent, ipAddress) {
  const userData = new UserData()
    .setEmail(order.customerEmail)  // Automatically hashed by SDK
    .setClientIpAddress(ipAddress)
    .setClientUserAgent(userAgent);

  const customData = new CustomData()
    .setValue(order.total)
    .setCurrency(order.currency)
    .setContentIds(order.lineItems.map(l => l.sku));

  const serverEvent = new ServerEvent()
    .setEventName('Purchase')
    .setEventTime(Math.floor(Date.now() / 1000))
    .setUserData(userData)
    .setCustomData(customData)
    .setEventId(eventId)   // Matches browser eventID — Meta deduplicates automatically
    .setActionSource('website');

  await new EventRequest(process.env.META_ACCESS_TOKEN, process.env.META_PIXEL_ID)
    .setEvents([serverEvent])
    .execute();
}

Initialize Google Consent Mode v2 (required for EU traffic as of March 2024):

javascript

// Must run BEFORE GTM or gtag.js loads
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}

gtag('consent', 'default', {
  ad_storage: 'denied',
  ad_user_data: 'denied',
  ad_personalization: 'denied',
  analytics_storage: 'denied',
  wait_for_update: 500,  // Wait for CMP to update consent
});

// After user accepts cookies via your CMP:
gtag('consent', 'update', {
  ad_storage: preferences.marketing ? 'granted' : 'denied',
  ad_user_data: preferences.marketing ? 'granted' : 'denied',
  analytics_storage: preferences.analytics ? 'granted' : 'denied',
});

Validate events before deploying:

bash

undefined

首先设计标准数据层——无论哪个供应商使用，每个事件都遵循相同格式：

javascript

// dataLayer必须在GTM加载前在<head>中初始化
window.dataLayer = window.dataLayer || [];

// 推送新事件前务必清空ecommerce（防止GTM合并旧数据）
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'USD',
    value: product.price * quantity,
    items: [{
      item_id: product.sku,
      item_name: product.name,
      item_brand: product.brand,
      item_category: product.category,
      price: product.price,
      quantity,
    }],
  },
});

购买事件（订单确认后触发，使用服务器生成的订单ID作为
transaction_id
）：

javascript

window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: order.id,  // 必须唯一——用于浏览器与服务器事件的去重
    value: order.total,
    tax: order.tax,
    shipping: order.shippingCost,
    currency: order.currency,
    coupon: order.couponCode || '',
    items: order.lineItems.map(line => ({
      item_id: line.sku,
      item_name: line.name,
      price: line.unitPrice,
      quantity: line.qty,
    })),
  },
});

支持去重的Meta Pixel与Conversions API——使用共享的

event_id

同时从浏览器和服务器发送同一事件：

javascript

// 浏览器端——传递event_id用于去重
const eventId = `purchase_${order.id}`;
fbq('track', 'Purchase', {
  value: order.total,
  currency: order.currency,
  content_ids: order.lineItems.map(l => l.sku),
  content_type: 'product',
}, { eventID: eventId });

// 将eventId发送至服务器以同步Conversions API
await fetch('/api/analytics/meta-purchase', {
  method: 'POST',
  body: JSON.stringify({ orderId: order.id, eventId }),
});

javascript

// 服务器端Conversions API（Node.js）
import { ServerEvent, EventRequest, UserData, CustomData } from 'facebook-nodejs-business-sdk';

export async function sendMetaPurchase(order, eventId, userAgent, ipAddress) {
  const userData = new UserData()
    .setEmail(order.customerEmail)  // SDK会自动哈希处理
    .setClientIpAddress(ipAddress)
    .setClientUserAgent(userAgent);

  const customData = new CustomData()
    .setValue(order.total)
    .setCurrency(order.currency)
    .setContentIds(order.lineItems.map(l => l.sku));

  const serverEvent = new ServerEvent()
    .setEventName('Purchase')
    .setEventTime(Math.floor(Date.now() / 1000))
    .setUserData(userData)
    .setCustomData(customData)
    .setEventId(eventId)   // 与浏览器端eventID匹配——Meta会自动去重
    .setActionSource('website');

  await new EventRequest(process.env.META_ACCESS_TOKEN, process.env.META_PIXEL_ID)
    .setEvents([serverEvent])
    .execute();
}

初始化Google Consent Mode v2（自2024年3月起，欧盟流量要求必须配置）：

javascript

// 必须在GTM或gtag.js加载前运行
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}

gtag('consent', 'default', {
  ad_storage: 'denied',
  ad_user_data: 'denied',
  ad_personalization: 'denied',
  analytics_storage: 'denied',
  wait_for_update: 500,  // 等待CMP更新同意状态
});

// 用户通过CMP接受Cookie后：
gtag('consent', 'update', {
  ad_storage: preferences.marketing ? 'granted' : 'denied',
  ad_user_data: preferences.marketing ? 'granted' : 'denied',
  analytics_storage: preferences.analytics ? 'granted' : 'denied',
});

部署前验证事件：

bash

undefined

GA4 Measurement Protocol validation (returns hit validation report)

GA4 Measurement Protocol验证（返回命中验证报告）

curl -X POST
"https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET"
-H "Content-Type: application/json"
-d '{"client_id":"test-123","events":[{"name":"purchase","params":{"transaction_id":"T-001","value":59.99,"currency":"USD"}}]}'

undefined

undefined

Best Practices

最佳实践

Clear
ecommerce: null
before every e-commerce push — GTM merges data layer objects, so stale item arrays from a previous event will contaminate the next one
Use your server-generated order ID as
transaction_id
— never generate it on the client; this ensures deduplication works when both browser and server events fire
Send Conversions API events from a post-payment webhook — webhook delivery is more reliable than the client completing a fetch call during checkout
Gate
purchase
events behind idempotency checks — store fired
```
transaction_id
```
values in sessionStorage and skip re-firing if the confirmation page is reloaded
Use GTM environments for staging — test GTM changes in a staging environment so QA traffic never pollutes live reports

每次推送电商事件前清空
ecommerce: null
——GTM会合并数据层对象，因此上一个事件的旧商品数组会污染下一个事件的数据
使用服务器生成的订单ID作为
transaction_id
——绝不要在客户端生成，这能确保浏览器与服务器事件同时触发时去重功能正常
通过支付后Webhook发送Conversions API事件——Webhook交付比结账期间客户端完成fetch调用更可靠
为
purchase
事件添加幂等性检查——将已触发的
```
transaction_id
```
存储在sessionStorage中，若确认页面被重新加载则跳过重复触发
使用GTM环境进行 staging 测试——在 staging 环境中测试GTM变更，确保QA流量不会污染实时报告

Common Pitfalls

常见问题与解决方案

Problem	Solution
Duplicate purchase events in GA4	Check `sessionStorage.getItem('purchase_fired_' + order.id)` before pushing; set it after the push fires
Items array empty in GTM	Forgot to push `{ ecommerce: null }` before the event — GTM caches the previous items array
Meta Pixel and Conversions API both counting conversions	Pass matching `eventID` (browser) and `event_id` (server) — Meta deduplicates on this field
Shopify GA4 funnel shows no data	Verify the GA4 Measurement ID in Online Store → Preferences matches your property; check GA4 DebugView to confirm events are firing
MonsterInsights not tracking WooCommerce orders	Ensure the Pro license is active (Enhanced eCommerce requires Pro); clear any caching plugins after installation

问题	解决方案
GA4中出现重复购买事件	推送前检查 `sessionStorage.getItem('purchase_fired_' + order.id)` ；推送完成后设置该值
GTM中商品数组为空	忘记在事件前推送 `{ ecommerce: null }` ——GTM缓存了之前的商品数组
Meta Pixel与Conversions API均统计转化	传递匹配的 `eventID` （浏览器端）和 `event_id` （服务器端）——Meta会基于该字段自动去重
Shopify GA4漏斗无数据	验证在线商店 → 偏好设置中的GA4测量ID是否与媒体资源匹配；检查GA4调试视图确认事件是否触发
MonsterInsights未跟踪WooCommerce订单	确保专业版许可证已激活（增强型电商功能需要专业版）；安装后清除缓存插件

analytics-integration

Original

Translation

Analytics Integration

分析工具集成

Overview

概述

When to Use This Skill

适用场景

Core Instructions

核心操作指南

Step 1: Determine your platform and recommended approach

步骤1：确定平台与推荐方案

Step 2: Platform-specific analytics setup

步骤2：平台专属分析配置

Shopify

Shopify

WooCommerce

WooCommerce

BigCommerce

BigCommerce

Custom / Headless

自定义/无头电商

GA4 Measurement Protocol validation (returns hit validation report)

GA4 Measurement Protocol验证（返回命中验证报告）

Best Practices

最佳实践

Common Pitfalls

常见问题与解决方案

Related Skills

相关技能