全渠道数据整合：广告/社交平台 S2S 对接手册（Meta / TikTok / Google Ads / SA360）

目标：把“外部流量来源（广告/搜索/社交）”与“站内行为（浏览/加购/下单/复购）”通过 双向 Server-to-Server (S2S) 闭环打通，形成可用于 个性化推荐/人群分层/投放优化 的统一客户数据资产。

本文聚焦 API 级生态打通：前置权限、对接流程、关键数据流、能拿到什么数据/拿不到什么数据，以及可落地的字段模型与案例。

---

1. 先统一一个关键认知：平台“能给你的” vs “你必须自己采的”

1.1 平台通常不会直接把“站内原始行为流”推给你

• 平台能提供：广告侧数据（投放结构、展示/点击/花费、部分归因结果、部分搜索词/查询报表）。
• 平台不能提供：你站内的完整浏览路径、SKU 级加购细节、支付方式、用户在站内的每一步行为日志（这些是商家数据资产，不会被平台主动回传给第三方）。

所以，“实时行为同步”的工程实现，本质是：

• 你采集站内事件（JS SDK / App SDK / Webhook / 商家后端）→ 写入你的事件流系统
• 你把关键事件回传给平台（Meta CAPI / TikTok Events API / Google Ads Conversion Upload）→ 平台用 click id / user identifiers 做匹配与归因
• 你再从平台拉报表做补全/归因标签富化（Marketing API / Reporting API / Google Ads API GAQL / SA360 Reporting）

---

2. 双向 S2S 的统一数据流（适用于 Nosto 同类系统）

2.1 统一闭环图（建议你们 SaaS 的标准实现）

用户点击广告/搜索/社交流量
  └─> 落地页 URL 带 click_id（fbclid / ttclid / gclid / wbraid / gbraid）与/或 UTM
       └─> 商家前端：JS SDK 解析并写入一方 Cookie（_fbc/_fbp/_ttp/your_cookie）
            └─> 事件上报到 SaaS（前端 -> SaaS 采集 API）
                 └─> 商家后端：下单/支付/退款等用 S2S 回传 SaaS（server->server）
                      ├─> SaaS：写入 Kafka/日志/画像（实时推荐/分群用）
                      └─> SaaS：向广告平台回传转化（Meta CAPI / TikTok Events API / Google Ads Upload）
                           └─> SaaS：定时从平台拉报表（campaign/ad/keyword/search term/成本）
                                └─> 富化“归因标签”，沉淀到 Customer 360

2.2 你们需要沉淀的“归因标签”（Attribution Tags）建议字段

建议把归因信息当作“可被实时更新的用户画像字段”，而不是一次性埋在订单里。

• 基础来源：
  • traffic_source：meta / tiktok / google_ads / sa360 / organic / direct / referral
  • utm_source / utm_medium / utm_campaign / utm_term / utm_content
  • landing_page_url、referrer（注意合规与脱敏）
• 点击标识（最关键）：
  • meta.fbclid（URL 参数）、meta.fbp、meta.fbc（一方 cookie 值）
  • tiktok.ttclid（URL 参数）、tiktok.ttp（一方 cookie 值）
  • google.gclid / google.wbraid / google.gbraid（URL 参数）
• 投放结构（从平台报表富化而来）：
  • campaign_id / campaign_name
  • adset_id（Meta）/ adgroup_id（TikTok/Google）/ ad_group_id（Google）
  • ad_id / creative_id / placement（平台字段不同，统一映射）
• 搜索意图（仅限付费搜索场景）：
  • search_term（注意：Google Ads 受隐私阈值影响可能为空或被归为 “other search terms”）
  • keyword / keyword_id / match_type（更稳定，建议优先用）

---

3. Meta（Facebook/Instagram）：合作伙伴模式 / Marketing API / Conversions API

参考：https://developers.facebook.com/docs/marketing-api/、https://developers.facebook.com/docs/marketing-api/conversions-api/

3.1 前置条件（商家侧 & SaaS 侧）

• 商家侧必须具备：
  • Business Manager / 资产（Ad Account、Pixel、Domain 等）
  • 能授权你们访问广告账户数据（最小化权限）
  • 站点已部署 Pixel（可选但强烈建议）或至少能在站点生成并持久化 _fbp/_fbc
• SaaS 侧必须具备：
  • Meta 开发者应用（App ID/Secret）
  • OAuth 能力（获取并续期 token）
  • CAPI 事件接入与去重能力（event_id/event_name/event_time 去重）

3.2 对接流程（建议的合作伙伴实现）

A) 授权与凭证

• 商家在你们后台点击“连接 Meta” → 跳转 Meta OAuth → 授权广告资产访问权限
• 你们获取 token 后，长期安全存储（加密、分租户隔离），并做定期续期/失效告警

常见权限 scope（按需最小化申请）：

• ads_read：读取投放与报表
• ads_management：如需代管投放才需要
• business_management：如需读取/管理 Business 资产才需要

B) 数据流 1：从 Meta 拉“广告侧数据/报表”

典型用途：

• 把 campaign_id/adset_id/ad_id/creative_id、花费、展示、点击等富化到你们的归因标签
• 做广告人群与站内行为联动分析（例如“某 campaign 带来的用户偏好/复购”）

典型 API：

• Insights（聚合报表）：展示、点击、花费、CTR、转化（取决于像素/回传是否就绪）
• 对象层级：Campaign / AdSet / Ad / Creative 元数据

重要边界：报表数据通常是 聚合 的；你无法从 API 拿到“每次点击对应的某个具体用户的 PII”。

C) 数据流 2：向 Meta 回传“站内关键事件”（Conversions API, CAPI）

用途：

• 提升归因完整性（浏览器拦截、Cookie 限制、跨设备场景）
• 让 Meta 的投放优化更准确（事件质量更好 → 算法更容易学习）
• 同时你们自己也获得“更完整的事件流”（用于推荐/分群/AB）

事件回传关键字段（概念级）：

• event_name：例如 PageView / ViewContent / AddToCart / Purchase
• event_time：秒级时间戳
• event_id：用于去重（与 Pixel 端一致时可实现跨端去重）
• action_source：例如 website / app / email（以官方要求为准）
• user_data：用于匹配的用户标识（哈希邮箱/哈希手机号/external_id、以及 fbp/fbc 等）
• custom_data：订单/商品信息（value/currency/content_ids/contents 等）

标识符串联机制（你问的“浏览器哪个字段告诉我是 Facebook 来的？”）：

• 用户点击 Meta 广告进入落地页时，URL 往往携带 fbclid
• 站点 Pixel/你们 SDK 可据此生成/写入一方 cookie：
  • _fbp：浏览器级标识（first-party cookie）
  • _fbc：点击级标识（通常由 fbclid 派生）
• 回传 CAPI 时带上 fbp/fbc +（可选）哈希 PII → Meta 服务器能把“站内事件”与“广告点击/曝光”匹配，进而给出归因并用于投放优化

你之所以“要回传给 Facebook”，不是为了让它把站内行为“回传给你”，而是为了让它把你采到的站内事件纳入它的归因与优化体系；之后你可以再拉报表把 campaign 等信息补全到你自己的画像里。

3.3 Meta：能拿到什么数据 / 拿不到什么数据（落到你们 SaaS 视角）

• 能拿到（通过 API 拉取）：
  • 投放结构：campaign/adset/ad、创意、预算、出价策略（视权限）
  • 聚合效果：impressions/clicks/spend/ctr/cpc 等
  • 聚合转化：哪些事件发生了多少次（前提是 Pixel/CAPI 打通）
• 能拿到（通过 URL/一方 cookie 采集）：
  • fbclid、_fbp、_fbc（用于“把外部点击与站内事件串起来”）
• 拿不到（或不建议/不允许拿）：
  • “某一次点击对应的用户真实身份/邮箱/手机号”——除非用户在你站内主动提供且合规授权，你也只能以哈希形式用于匹配
  • 用户在 Meta 内的完整行为轨迹（点赞了哪些内容、浏览了什么）——广告 API 不会给到这种用户级别明细

---

4. TikTok：Marketing API / Events API（TikTok Pixel / Events）

参考：https://developers.tiktok.com/、https://ads.tiktok.com/marketing_api/docs

4.1 前置条件

• 商家侧：
  • TikTok Business Center / Ads Account（能授权）
  • 站点可部署 TikTok Pixel（可选但建议）
• SaaS 侧：
  • TikTok 开发者应用（用于 OAuth/授权）
  • 能安全存储/续期 token（分租户隔离）
  • Events API 回传能力（含去重、重试、签名/鉴权）

4.2 数据流 1：从 TikTok 拉报表（投放结构与聚合指标）

典型用途：

• 富化 campaign/adgroup/ad 元数据与聚合指标（展示、点击、花费、转化等）
• 做“投放 → 站内偏好 → 推荐策略”的闭环分析

边界同 Meta：报表以聚合为主，不会给你用户级 PII。

4.3 数据流 2：向 TikTok 回传站内事件（Events API）

关键点与 Meta 类似：你们采集站内事件后，把关键事件用 S2S 回传给 TikTok，提升匹配与归因。

关键标识符：

• ttclid：用户点击广告的 click id（落地页 URL 参数）
• _ttp：TikTok 常用的一方 cookie 标识（由 Pixel/SDK 生成或你们 SDK 兼容生成）
• external_id / 哈希邮箱/哈希手机号：用于增强匹配（必须合规）

事件字段（概念级）：

• event（Purchase/AddToCart/ViewContent 等）
• event_time
• event_id（去重）
• user（ttclid/ttp/external_id/hashed identifiers）
• properties（value/currency/content_id/contents 等）

4.4 TikTok：能拿到什么 / 拿不到什么

• 能拿到：
  • 投放结构与聚合效果（报表）
  • 通过 ttclid/_ttp 与回传事件实现“点击→站内行为”的串联
• 拿不到：
  • TikTok 站内用户级行为明细（除非是你们有单独的社交内容产品授权场景；广告侧通常不给）

---

5. Google Ads（含 Google Search Ads）：Google Ads API / Conversion Upload / Search Terms

参考：https://developers.google.com/google-ads/api/docs/start

5.1 前置条件

• 商家侧：
  • Google Ads 账户
  • 已创建 Conversion Action（或由你们引导创建）
  • 开启 Auto-tagging（使落地页带 gclid/wbraid/gbraid 等 click id）
• SaaS 侧：
  • Google Cloud 项目 + OAuth 客户端
  • Google Ads API 开发者令牌（developer token）
  • token 安全存储与续期

5.2 数据流 1：从 Google Ads 拉报表（GAQL）

你们主要用 Google Ads API 的 GAQL（Google Ads Query Language）去拉 结构化投放数据 + 聚合指标，用于富化你们的归因标签与运营分析。

你能稳定拿到的（建议优先依赖）

• 投放结构：campaign / ad group / ad / asset（命名与层级）
• 聚合指标：impressions / clicks / cost / conversions / conversion_value 等
• 分段（segments）：
  • date（按天）
  • device（移动/桌面等）
  • network（Search/Display 等，视口径）

重要边界：Google Ads 报表默认是“聚合”视角，通常并不会给你“每一次点击的明细日志”，更不会给你“点击对应的用户身份”。

付费搜索词（search term）到底能不能拿到？

需要严格区分：

• 能拿到（Paid Search Search Terms）：广告投放的搜索查询词（Search Terms / Search Query Report），前提是该账户投放了搜索广告，且该维度在报表/隐私规则下可用。
• 拿不到（Organic Keyword）：自然搜索（SEO）的关键词，Google 多年前起就不再对外提供用户级自然搜索词（常见为 (not provided) 现象）。

此外，Google 对 Search Terms 还有典型限制：

• 隐私阈值/脱敏：部分查询词会被归为“其他搜索词（other search terms）”或直接不可见。
• 延迟：search term 通常不是秒级实时（常见为小时级到次日级），不适合作为你们“实时推荐”的唯一输入。

工程建议：在“实时推荐”侧，不依赖明文 search_term，而优先使用更稳定的：

• campaign_id / ad_group_id / keyword_id / match_type
• 以及你们自己通过落地页参数/站内行为构建的“意图标签”（例如“来自 running shoes 广告组的用户”）

SaaS 如何更容易拿到“投放结构/关键词意图”？

最佳实践不是等平台回传，而是让商家（或你们插件）在最终落地页上带上可解析参数：

• Auto-tagging：保留 gclid/wbraid/gbraid（用于转化上传与匹配）
• ValueTrack/URL 模板：把投放结构写进落地页参数（用于你们实时侧富化）

示例（概念）：

Final URL Suffix:
utm_source=google&utm_medium=cpc&utm_campaign={campaignid}&utm_content={creative}&utm_term={keyword}
&g_campaign_id={campaignid}&g_adgroup_id={adgroupid}&g_ad_id={creative}&g_kw={keyword}&g_mt={matchtype}

这样，你们即使不即时拉 Google 报表，也能在“用户首次进入时”就把归因标签写入画像，满足实时推荐。

5.3 数据流 2：向 Google Ads 回传转化（Conversion Upload）

核心用途：

• 把你们采集到的站内关键事件（Purchase/Lead 等）回传给 Google，使其归因与投放优化成立
• 同时你们自己沉淀“点击 → 站内行为 → 订单”的闭环数据

两类常见回传

• 点击转化（Click Conversions）：用 gclid（以及移动/隐私场景下的 wbraid/gbraid）上传转化
• 增强型转化（Enhanced Conversions）：在合规前提下，附加哈希邮箱/哈希手机号等用户标识提升匹配率

你们侧必须实现的关键字段（概念级）

• click_id：gclid 或 wbraid 或 gbraid（三者至少其一，按场景）
• conversion_action：对应商家的转化目标（由商家/你们引导配置）
• conversion_date_time：转化发生时间（带时区）
• conversion_value、currency_code
• order_id（强烈建议）：用于去重与退款/撤单对账

去重策略：你们内部建议以 tenant_id + order_id + event_name 或 event_id 做幂等；对外回传也尽量保证同一订单不会重复上传。

5.4 SaaS 如何拿到 gclid / wbraid / gbraid（回答“独立站 SaaS 怎么拿”）

这类 click id 出现在 商家站点的落地页 URL 上；SaaS 拿到它的方式不是“从 Google 拉”，而是：

• 商家前端采集：你们提供 JS SDK / 插件脚本，解析 URL 参数并写入一方 cookie，然后上报给你们的采集 API
• 商家后端绑定订单：下单/支付成功时，商家后端把“订单号 ↔ click id ↔ anonymous_id/user_id”用 S2S 发给你们

这就是 Nosto 这类系统的关键点：你们掌握‘站内事件流’与‘入口 click id’，平台只负责‘归因/报表/投放优化’那部分。

---

6. Google Search Ads vs Search Ads 360 (SA360)

6.1 概念澄清

• Google Search Ads（搜索广告）：通常指 Google Ads 里的搜索广告 Campaign（你们通过 Google Ads API 接即可）
• Search Ads 360（SA360）：面向更大体量/多引擎管理的企业级平台（可能有独立的报表/转化口径，如 Floodlight）

参考：https://developers.google.com/search-ads

6.2 SA360 的典型对接模式（你们 SaaS 应该怎么做）

你们要做的是“可选的企业版集成”，不建议让 MVP 强依赖 SA360。

• 数据流 1：报表拉取：
  • 拉 campaign/keyword/engine account 等维度的聚合报表（展示、点击、花费、转化）
  • 用于富化你们的归因标签（尤其是多搜索引擎统一口径时）
• 数据流 2：转化回传：
  • 企业广告主常用 Floodlight/离线转化机制，你们把站内 Purchase/Lead 等按其口径回传

SA360 的关键不是“多拿到什么用户行为”，而是“多一套企业广告管理口径与归因配置”。你们的站内事件采集方式不变。

---

7. 两个端到端案例（把“能拿到什么数据”讲透）

7.1 案例 A：Meta 广告 → 商品页浏览 → 加购 → 下单（CAPI 闭环）

前置：

• 商家已连接 Meta（OAuth token 已存）
• 站点能采集 fbclid 并持久化 _fbp/_fbc

时间线：

1) 用户点击 Instagram 广告：

• 进入：/product/sku123?...&fbclid=XXXX&utm_source=instagram&utm_medium=cpc&utm_campaign=summer
• 你们 JS SDK：
  • 解析 fbclid
  • 写入/更新 _fbc，读取/生成 _fbp
  • 上报给 SaaS：anonymous_id + fbclid/fbp/fbc + utm_* + landing_page_url

2) 用户浏览商品：

• 上报事件：ViewContent（包含 content_id=sku123）
• 你们实时画像：把 traffic_source=meta、campaign=summer 等写入用户画像（用于实时推荐：比如同系列商品、同 campaign 热门 SKU）

3) 用户加购：

• 上报事件：AddToCart

4) 用户下单支付：

• 商家后端 S2S → SaaS：Purchase（包含 order_id/value/currency/items）
• SaaS → Meta CAPI：回传 Purchase（带 event_id、fbp/fbc、可选哈希邮箱/手机号）

你们最终能沉淀的数据：

• 入口归因标签：meta + utm + fbclid/fbp/fbc
• 站内行为序列：view → add_to_cart → purchase（SKU 级）
• 广告侧富化（后续拉报表）：campaign/adset/ad 的花费与聚合转化，绑定到你们的 campaign 维度分析

7.2 案例 B：Google 搜索广告 → 落地页 → 下单（Click Conversion Upload）

前置：

• 商家开启 Auto-tagging
• 你们 JS SDK 能采集 gclid/wbraid/gbraid
• 商家/你们配置好 Conversion Action

时间线：

1) 用户点击 Google 搜索广告进入：

• URL 带 gclid=...（或隐私/移动场景下带 wbraid/gbraid）
• 你们 SDK 上报 click id 与落地页参数
• 若商家配置了 URL 模板，你们还能直接拿到 campaignid/adgroupid/keyword/matchtype（用于实时意图标签）

2) 用户下单：

• 商家后端 S2S → SaaS：Purchase(order_id, value, currency, click_id)
• SaaS → Google Ads：上传 click conversion

你们最终能沉淀的数据：

• click id 与订单绑定（用于归因与广告优化）
• 实时意图标签（来自落地页参数/广告组/keyword 维度）
• 次日/小时级补全的 search term（可用时）与成本指标（用于归因分析与投放策略联动）

---

8. 你们实现这套系统时的工程清单（强烈建议）

8.1 接入 API（你们 SaaS 侧）最小闭环

• 采集 API（前端/SDK）：
  • /collect：行为事件（view/search/add_to_cart/purchase…）
  • /attribution：入口 click id / utm / referrer（也可并入 collect）
• 商家后端回传 API：
  • /orders：下单/支付/退款/撤单（确保最终一致性）
• 平台连接 API：
  • /oauth/meta/callback、/oauth/tiktok/callback、/oauth/google/callback
  • /integrations/{platform}/status

8.2 三件套：幂等、重试、限流

• 幂等：event_id/order_id 贯穿全链路；Kafka 消费端也要幂等
• 重试：对外回传失败要有队列与退避重试（避免阻塞主链路）
• 限流：按租户与平台维度限流，避免某租户爆量拖垮公共资源

8.3 合规与隐私（必须前置）

• 同意管理：把 consent 状态作为事件字段（例如 consent.ad_storage/analytics_storage），决定是否回传/是否存储某些标识符
• 哈希规则：邮箱/手机号必须标准化后再哈希（SHA-256 等），只在“用于匹配”的必要范围内传输
• 数据最小化：不收集不必要的 PII；对 referrer/landing_url 做脱敏与参数白名单

---

9. 参考链接（官方入口）

• Meta / Facebook
  • Meta Conversions API
  • Meta Marketing API
  • Facebook Login（OAuth 手动流程）
• Google
  • Google Ads API（Start）
  • Google Ads API OAuth（Overview）
• TikTok
  • TikTok for Business / Marketing API Docs
  • TikTok Events API（文档入口）