docs/%E5%85%A8%E6%B8%A0%E9%81%93%E6%95%B0%E6%8D%AE%E6%95%B4%E5%90%88-%E5%B9%BF%E5%91%8A%E5%B9%B3%E5%8F%B0S2S%E5%AF%B9%E6%8E%A5%E6%89%8B%E5%86%8C.md

# 全渠道数据整合：广告/社交平台 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 模板**：把投放结构写进落地页参数（用于你们实时侧富化）
示例（概念）：
```text
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` 做脱敏与参数白名单