ad-tracking

广告分析与转化跟踪集成

将 Google Analytics 4、Google Ads、Meta（Facebook）Pixel 和 LinkedIn Insight Tag 集成到 Web 应用的完整参考，涵盖适当的同意管理、标准事件映射、用户识别以及 GDPR/DMA 合规性。

---

本指南涵盖内容

GA4、Google Ads、Meta Pixel 和 LinkedIn Insight Tag 均受 Consent Mode v2 管理。正文介绍最精简的设置和常见陷阱；表格、架构及各框架的接线配置位于 references/，详见文末。

架构概览

现代广告分析技术栈由多个像素/标签组成，它们必须遵循相同的同意状态。架构遵循以下模式：

┌──────────────────────────────────────────────────────────┐
│                    CONSENT LAYER                          │
│  Cookie Consent Banner → localStorage → consent state     │
│  All pixels gated by the same consent storage key         │
└────────────────────┬─────────────────────────────────────┘
                     │ granted / denied
     ┌───────────────┼──────────────────┬──────────────────┐
     ▼               ▼                  ▼                  ▼
┌─────────┐   ┌────────────┐   ┌──────────────┐   ┌────────────┐
│  GA4 +   │   │  Meta      │   │  LinkedIn    │   │  Mixpanel  │
│  Google  │   │  Pixel     │   │  Insight     │   │  (product  │
│  Ads     │   │  (fbq)     │   │  Tag         │   │  analytics)│
└─────────┘   └────────────┘   └──────────────┘   └────────────┘
     │               │                  │                  │
     ▼               ▼                  ▼                  ▼
  Consent         Consent-gated     Consent-gated      Consent-gated
  Mode v2         (render only      (render only        (opt_in /
  (built-in)      when granted)     when granted)       opt_out)

关键原则： GA4 使用内置的 Consent Mode v2（默认拒绝，在获得同意后更新）。所有其他像素（Meta、LinkedIn、Mixpanel）采用同意门控模式——只有在用户授予同意后才会渲染。共享的 CustomEvent 可在不重新加载页面的情况下动态更改同意状态。

---

同意

有关七种同意信号、Advanced 与 Basic 模式、特定地区的默认设置、精细化同意和 GTM 接线配置，请阅读 references/consent-mode.md。自 2024 年 3 月起，在欧盟/欧洲经济区必须使用 Consent Mode v2。

顺序至关重要，出错时不会有明显迹象：

1. dataLayer init + gtag() stub
2. gtag('consent', 'default', { …'denied', wait_for_update: 500 })
3. restore a stored decision → gtag('consent', 'update', …)
4. load gtag.js (async)
5. gtag('js', new Date()) + gtag('config', TAG_ID)

步骤 1–3 必须在 gtag.js 加载前同步运行。若在脚本加载后才设置默认值，那么在所有以接受同意作为起点的测试中，页面看起来都会正常，但拒绝同意的用户群体会完全丢失。

拒绝同意不等于关闭。 使用 Advanced 模式时，Google 仍会收到无 Cookie 的 ping，并据此对转化进行建模（Google 自己发布的案例研究中提到的比例约为 65–70%；在测量之前，无法得知你的实际比例）。预先征得同意前发送 ping 在你所在司法管辖区是否合法，应由法律顾问判断——Basic 是更谨慎的模式，而且仍能使用 Google 的通用建模。

Google Analytics 4

设置

环境变量： NEXT_PUBLIC_GA_MEASUREMENT_ID（格式：G-XXXXXXXXXX）

脚本加载：

<script>
  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
  });
  // Restore prior consent
  try {
    if (localStorage.getItem('consent_key') === 'granted') {
      gtag('consent', 'update', {
        ad_storage: 'granted', ad_user_data: 'granted',
        ad_personalization: 'granted', analytics_storage: 'granted'
      });
    }
  } catch(e) {}
</script>


<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>


<script>
  gtag('js', new Date());
  // GA4 config carries NO allow_enhanced_conversions — that flag belongs on the
  // Google Ads `AW-` tag only (see the Enhanced-conversions section); on a `G-`
  // tag it enables nothing and contradicts this skill's own rule.
  gtag('config', 'G-XXXXXXXXXX');
</script>

命令和事件

请阅读 references/gtag-api.md → 命令，了解 config / event / set / get / consent 的参数作用域和优先级；并阅读 references/event-tracking.md → 推荐事件，了解 Google Ads 可导入的 GA4 事件名称 （sign_up、login、begin_checkout、purchase、 generate_lead、view_item）及其必需参数。

自行发送 SPA 页面浏览事件时，不会自动跟踪。 增强型衡量会在 History API 发生变化时触发 page_view；若在路由更改时再手动发送一次，每次导航都会被重复计数。只有在使用哈希路由时才发送手动页面浏览事件。

SPA 页面跟踪

启用增强型衡量的 GA4 会通过 History API 自动跟踪单页应用的 page_view。只有使用哈希路由（#/path）时才需要手动跟踪 page_view。同意状态会在 SPA 路由更改期间保持不变。

文档：

• 设置 Google tag
• gtag.js API 参考
• 推荐事件
• 事件参数
• 数据路由与组

---

Google Ads 转化跟踪

架构

GA4 和 Google Ads 共用同一段 gtag.js 代码片段。设置 NEXT_PUBLIC_GOOGLE_ADS_ID（格式：AW-XXXXXXXXX）后，添加第二个 config 调用：

gtag('config', 'G-XXXXXXXXXX');  // GA4
gtag('config', 'AW-XXXXXXXXX');  // Google Ads

两者共用同一同意状态、第一方 Cookie 和 dataLayer 管道。

增强型转化

增强型转化通过将经过哈希处理的用户数据（电子邮件、电话号码）与 Google 账号匹配来提升归因效果。设置：

1. 只有在需要使用此标记时，才应将它添加到 Google Ads 配置——AW- 标记，而不是 GA4 的 G- 标记（此技能的早期版本曾将它加到 G- 配置中，这对 Ads 不起任何作用）：

gtag('config', 'AW-XXXXXXXXX', { allow_enhanced_conversions: true });

已于 2026-08-30 检查：Google 当前的设置文档 （support.google.com/google-ads/answer/9888145、…/13258081）已不再说明此标记——当前生效的机制是账号级开关（步骤 3）加上 user_data（步骤 2）。如果现有标记已包含此标记，可保留；不要将它复制到 G- 配置中。

2. 在转化事件触发前设置用户数据：

gtag('set', 'user_data', {
  email: '[email protected]',        // Google hashes automatically
  phone_number: '+1234567890',       // optional
});

3. 在 Google Ads 控制台中启用：目标 → 转化 → 设置 → 增强型转化 →“启用增强型转化”（已于 2026-08-31 对照 support.google.com/google-ads/answer/13258081 检查；重新设计后的界面已移除旧版“工具 → 转化”路径）

user_id（跨设备跟踪）

用户完成身份验证后设置 GA4 user_id，以启用跨设备跟踪和受众群体构建：

gtag('config', 'G-XXXXXXXXXX', {
  user_id: 'USER_123',
  send_page_view: false    // prevent duplicate page_view
});

通过外部重定向保留 gclid

Google Ads 自动标记产生的 gclid 会存储在 _gcl_aw 第一方 Cookie 中（默认有效期约为 90 天）。它能够在外部重定向（Stripe Checkout → 返回 URL）过程中保留，因为只有过期才会使自有域名上的 Cookie 失效——无需额外代码。已于 2026-08-31 检查；需要注意的是 Safari，其 ITP 会将 JS 设置的 Cookie 有效期限制为 7 天；如果用户通过带链接装饰的导航进入页面（gclid 落地页即属此类），则限制为 24 小时。

Google Ads 控制台设置

阅读 references/gtag-api.md → 多产品配置，了解如何将一个 gtag 加载器同时连接到 GA4 和 Ads。在 Ads 控制台中，转化操作必须设为 主要，并且必须在首次点击到达前设置好归因窗口；否则，早期转化会按照旧设置进行归因，且无法重新计算。

Meta（Facebook）Pixel

设置

环境变量： NEXT_PUBLIC_META_PIXEL_ID（数字字符串）

基础代码（受同意状态控制）：

!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}
(window,document,'script','https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'PIXEL_ID');
fbq('track', 'PageView');

noscript 后备方案——受同意状态控制，或省略。 裸写的 <noscript> Meta Pixel 会在每次禁用 JS 的页面浏览时触发——没有横幅、没有 fbq、也没有同意——这与本技术栈“只有在获得同意后才渲染 Meta”的规则相矛盾。因此，只能在服务器端输出，并且仅当已存在服务器可验证的同意状态（服务器在写入 HTML 前读取的签名 HttpOnly Cookie）时才输出。如果无法在服务器端验证同意状态，请省略它——Meta 的验证并不需要它，而且已触发的请求无法撤回：

{% if consent_cookie_verified and consent.ad_storage == "granted" %}
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id=PIXEL_ID&ev=PageView&noscript=1"/></noscript>
{% endif %}

此处的代码片段来自可执行模板，因此静态检查会阻止本节要避免的两种错误：在 G- 标记上设置 allow_enhanced_conversions，以及未通过服务器验证的同意状态判断就加载 noscript Meta Pixel。

标准事件

Meta 定义了 17 种标准事件。SaaS 转化漏斗中涉及的四种事件是 CompleteRegistration、InitiateCheckout、Purchase 和 Subscribe，其中只有 Purchase 具有必需参数：value 和 currency；缺少这些参数，Meta 就无法进行优化。完整表格——包括所有事件、参数和注意事项——请参阅 references/meta-linkedin.md → 标准事件。

Meta 和 LinkedIn 的更多细节

请阅读 references/meta-linkedin.md，了解各事件的参数对象、触发封装函数、高级匹配（哈希标识符以及绝不能发送的内容）和 CAPI 去重。

LinkedIn Insight Tag

与 Meta Pixel 使用相同的封装函数，受同意状态控制；环境变量为 NEXT_PUBLIC_LINKEDIN_PARTNER_ID。转化在 Campaign Manager 中配置，而不是在代码中配置，因此无需去重，也不会有任何内容在构建包中静默失效——但可刷新的页面若使用 URL 规则，每次刷新都会计数。设置代码片段、Campaign Manager 中的步骤以及 lintrk，请参阅 references/meta-linkedin.md → LinkedIn 转化跟踪。

用户识别

正文始终遵循一条规则，因为弄错会导致归因错误，而不只是丢失归因：先识别，再跟踪，绝不能反过来。以匿名 ID 触发、之后再重新归因的事件，对所有已接收该事件的平台来说，都会算作两个用户。各平台的策略、Mixpanel 中 alias 与 identify 的区别，以及时机规则，请参阅 references/event-tracking.md → 用户识别。

事件命名

请阅读 references/event-tracking.md → 推荐事件和参数规则。GA4 保留了一组名称，与之冲突的事件会被静默丢弃；参考文档列出了这些名称。

电子商务

请阅读 references/event-tracking.md → 电子商务事件，了解 GA4 商品架构以及完整的 purchase / add_to_cart / begin_checkout 事件集。

重复数据删除处理不当会悄悄让收入翻倍。 从浏览器和服务端（Conversions API、服务端 GA4）同时触发的 purchase 必须携带相同的 event_id / transaction_id，否则两者都会被计入。请运行 fixtures/assert-dedup-contract.mjs，而不要重新加载感谢页面：pixel-and-capi-carry-one-event-id 和 pixel-and-capi-carry-one-event-name 会让只共享其中一个字段的发送器测试失败，no-purchase-reported-before-the-charge-cleared 会让从重定向触发事件的发送器测试失败，而 the-browser-event-is-kept 会让丢弃像素事件的发送器测试失败。--self-test 会删除每条规则，并观察对应断言是否变红。

purchase 不是浏览器事件，这决定了它的来源。 列表中的其他事件都是用户在标签页中执行的操作，因此浏览器是其自然来源。purchase 是支付系统中成功扣款的结果，而只有服务提供商的 webhook 知道扣款是否成功。从感谢页面触发事件，意味着在一个完全不知道扣款是否成功的地方触发事件——这就是为什么每个访问过该页面的会话都会有一条 purchase 事件，却没有任何退款事件。

由此得出的结论是一个执行顺序，而不是偏好：

1. webhook 处理程序是 purchase 的事实来源。 它写入权益，并由同一处理程序发送服务端转化事件。如果资金是在处理程序中记录的，那么事件也应在那里触发。
2. 保留浏览器事件，但让它从属于服务端事件。 仅保留浏览器携带的归因信号（点击 ID、同意状态、会话），为其设置服务端将复用的 event_id，并在两者不一致时以服务端为准。
3. 浏览器会丢失的内容，都在最接近资金交易的环节丢失。 拦截器、移动浏览器在重定向时终止标签页、支付服务提供商的托管页面在返回跳转前结束会话——这些都会优先移除最后一步，因此仅由浏览器统计的 purchase 数量会偏低，且你无法在浏览器内测出偏差值。

请对账支付服务提供商的数据，而不是分析仪表板：某个时段内成功扣款的数量是支付系统能够准确提供的数字，也是唯一不属于遥测数据的外部核验方式。关于这项对账还能揭示哪些问题，请参阅 stripe-billing → 依赖单一服务提供商。

内容安全策略

请阅读 references/performance-security.md → 内容安全策略，了解各平台的完整指令集。

陷阱： 给 gtag 加载器设置 nonce 并不足够——Google 会在运行时注入其他脚本，因此 script-src 还需要包含 Google 域名；而且在落地页上通过的 CSP，仍可能在加载 Ads 转化标签的结账页面上造成故障。

Next.js

阅读 references/gtag-api.md → Next.js / React Integration，了解组件树；阅读 references/performance-security.md → Script Loading Strategies，了解 next/script 策略选择和 SPA 路由变更。

有两个不容易察觉的问题：

• NEXT_PUBLIC_* 会在构建时内联。在 Docker 构建中，该变量必须存在于构建阶段；如果在运行时注入，打包文件中就会保留字面字符串，所有事件都会无处可去。
• 已通过身份验证的区域和嵌入式 / 小组件页面需要不同的门控方式——仪表盘已有同意状态，嵌入式页面可能没有，不能假定它有父页面的同意状态。

UTM 归因

阅读 references/event-tracking.md → UTM Attribution，了解采集流程（通过 localStorage 跨越 OAuth 重定向并写入数据库）、五个参数的表格，以及平台点击 ID（gclid / fbclid / li_fat_id）——SDK 会自动处理这些 ID；不要从 URL 中移除它们。

---

验证

阅读 references/performance-security.md → Debug & Testing，了解完整的平台检查清单（GA4 DebugView、Meta Test Events、LinkedIn 标签助手）以及同意状态的往返流程。

**最能发现问题的检查方法：**在全新的无痕窗口中打开网站，拒绝同意，然后在 DevTools → Network 中确认没有设置 _ga 或 _gcl_* Cookie，且收集请求携带 gcs=G100。同意后标签能正常触发，却忽略了默认拒绝状态——这正是本技能要防止的问题；而在所有一开始就接受同意的测试中，它看起来都正常。

故障排除

阅读 references/performance-security.md → Troubleshooting，查看常见问题表格（同意状态顺序、重复的 PageView、Advanced/Enhanced Matching 时序、本地主机防护）和调试模式代码片段。最常见的两个问题是：同意状态 default 必须在 gtag.js 加载之前运行；没有 value / currency 的购买事件无法针对任一平台进行优化。

---

官方文档

Google：Consent Mode v2 · gtag.js · GA4 events。 Meta：Pixel · Conversions API。 LinkedIn：Insight Tag。 合规：EU DMA。

深入参考

以上各节涵盖四个平台的集成界面；本文刻意省略的详细内容则由这些文档提供。每篇文档开头都有自己的 Load this when 行，因此触发条件各有归属，本表也能保持为索引。

文件	适用场景
references/consent-mode.md	任务与同意状态有关
references/gtag-api.md	你要直接调用 gtag
references/event-tracking.md	你要设计事件架构
references/performance-security.md	标签影响 Lighthouse 分数或无法通过 CSP 检查
references/meta-linkedin.md	工作内容涉及 Meta 或 LinkedIn，而非 Google

关于同一问题中的页面速度方面——标签对 LCP 和 TBT 的影响，以及相应的处理方法——请参阅此资料包中的 frontend-performance 技能。

降级说明

• 不使用 Claude Code（Cursor、Codex、skills CLI、API 容器）：此工具包的 PreToolUse 门禁不会运行。它负责拒绝使用有效密钥或执行不可逆操作；在其他环境中，这些规则需要你手动遵守。
• 通过复制而非作为插件安装：原则会随之安装，但 hooks/ 不会——损失相同，补救方法也相同。
• 没有网络，或无法连接广告平台的 API：无法端到端验证服务器端事件。应说明去重检查未运行，而不是声称检查已通过； 浏览器像素触发只能证明浏览器正常，不能证明转化有效。

触发条件

还有一些会指向此处的短语：“广告跟踪”、“fbq”、“Google Ads”、“gtag”、“Cookie 同意”、“增强型转化”、“再营销”、“购买事件”、“gclid”、“UTM”、“归因”、“Cookie 同意”、“广告分析”。

已从 0.16.2 中的描述移至此处：“转化跟踪”。