docs/%E7%94%A8%E6%88%B7%E5%8C%B9%E9%85%8D%E4%B8%8E%E5%A4%96%E9%83%A8%E6%95%B0%E6%8D%AE%E6%89%93%E9%80%9A-%E5%B9%B3%E5%8F%B0%E5%AE%98%E6%96%B9%E6%9C%BA%E5%88%B6%E6%8F%90%E6%9D%83.md

# 用户匹配与外部数据打通：平台官方机制提权（Meta / Google Ads / TikTok）
> 本文是“提权版”总结：只聚焦 **用户匹配（Identity Resolution）** 与 **外部数据打通（Ad/Social/Search）** 两件事，基于平台官方机制（OAuth 授权、Server-to-Server 事件回传、报表/洞察拉取、Advanced Matching/Enhanced Conversions）整理成可落地的工程手册。
>
> 与整体 S2S 对接的关系：更完整的“全渠道闭环、归因标签字段、端到端案例”请见 `docs/全渠道数据整合-广告平台S2S对接手册.md`，本文不重复那部分，只做“匹配/打通”的深挖。
---
## 0. 提权结论（先给结论）
### 0.1 “用户匹配”在广告平台里到底是什么？
平台不会把“用户身份”回传给你；用户匹配的本质是：
- 你把**站内事件**（购买/加购/注册…）通过 S2S 回传给平台
- 事件里携带一组 **可匹配标识符**（click id、一方 cookie id、哈希化 PII、IP/UA 等）
- 平台用这些标识符把事件与其广告触达（点击/曝光/设备图谱）关联起来，从而：
  - 让平台的**归因/投放优化**成立（平台侧收益）
  - 让你能从平台报表拿到更准确的**聚合归因维度**（campaign/adgroup/keyword/cost…）并回灌你的 CDP/画像（你侧收益）
### 0.2 “外部数据打通”最稳定的三件套（跨平台通用）
按稳定性从高到低：
- **(1) click id / 广告点击链路标识**：`fbclid` / `ttclid` / `gclid` / `wbraid` / `gbraid`
- **(2) 一方标识符（first-party id）**：浏览器/设备侧的一方 cookie（例如 `_fbp/_fbc/_ttp` 等）+ 你们自己的 `anonymous_id`
- **(3) 哈希 PII（Advanced Matching / Enhanced Conversions）**：邮箱/手机号/姓名地址等标准化后 SHA-256（必须 consent + 合规）
> 真实世界落地建议：实时推荐/实时分群尽量依赖 (1)(2)；(3) 用于提升匹配率、跨设备、以及广告侧归因完整性。
### 0.3 跨设备（Cross-Device）在你们 SaaS 里怎么做“最小可用”？
不要一上来就做“设备指纹 + 概率图谱”作为主链路；MVP 最小闭环：
- **确定性合并**（Deterministic）：登录/下单/留资触发 `anonymous_id → user_id/email/phone` 合并
- **外部匹配增强**（Platform Matching）：在回传事件里带哈希邮箱/手机号 + click id + 一方 cookie id，让平台用它自己的跨设备图谱完成归因优化
- **你们内部**：沉淀 Identity Graph（节点=各种 ID，边=同人证据），后续再迭代概率匹配
---
## 1. 统一“可匹配标识符”字典（跨平台抽象）
建议你们内部事件模型统一下列字段（平台字段差异只在适配层解决）：
- **租户与用户**：
  - `tenant_id`
  - `anonymous_id`（你们 SDK 生成）
  - `user_id`（商家会员/登录用户）
- **入口与归因**：
  - `landing_url`（白名单参数、脱敏）
  - `referrer`（脱敏）
  - `utm_*`
  - `click_id`：`fbclid | ttclid | gclid | wbraid | gbraid`
  - `attribution_platform`：`meta | tiktok | google_ads | ...`
- **一方 cookie / 平台浏览器标识**：
  - `meta.fbp`、`meta.fbc`
  - `tiktok.ttp`
- **匹配增强（哈希 PII）**（可选，合规后启用）：
  - `email_sha256`
  - `phone_sha256`
  - （可扩展）姓名/地址等（不同平台支持程度不同）
- **设备/网络信号（通常作为辅助手段）**：
  - `client_ip`、`user_agent`
  - `device_type`、`os`、`browser`
> 关键：这些字段不是“为了把用户身份拿回来”，而是为了让 **平台能匹配、你能做 join**。
---
## 2. Meta（Facebook/Instagram）：官方授权机制 + Conversions API 用户匹配
参考（官方）：
- `https://developers.facebook.com/docs/marketing-api/conversions-api/`
- `https://developers.facebook.com/docs/facebook-login/`（OAuth/登录）
- `https://developers.facebook.com/docs/marketing-api/`（广告报表/洞察）
### 2.1 授权机制（合作伙伴常用形态）
你们会遇到两类“凭证来源”，工程上要分清：
#### A) 广告/报表类权限（读取投放结构与 Insights）
- 典型是 OAuth 授权后拿到 access token，再用 token 调用 Marketing API（读取账户、campaign、insights）
- 你们需要做：
  - token 加密存储、按 `tenant_id` 隔离
  - token 续期/失效处理
  - 权限最小化（常见 `ads_read` 起步）
#### B) CAPI 事件回传凭证（Pixel/数据源 Access Token）
- CAPI 常见方式是在 Events Manager / Pixel 设置里生成一个“用于回传事件的 token”
- 工程意义：这更像“写入凭证”，与“读取报表” token 可以不是同一个体系
> 提权点：**不要把 CAPI token 当作 OAuth token** 去做复杂权限管理；在你们 SaaS 里把它作为“数据源写入密钥”管理（可轮换、可禁用、可审计）。
### 2.2 用户匹配（Advanced Matching）在 CAPI 里怎么落地？
你回传事件时，Meta 侧的匹配信号主要来自三块：
- **点击链路**：`fbclid`（落地页 URL 参数）→ 你生成/保存 `fbc`
- **浏览器标识**：`fbp`（通常由 Pixel/你们 SDK 生成的一方 cookie）
- **哈希化 PII**：邮箱/手机号等（标准化后 SHA-256）
你们应该实现的“最低配 CAPI user_data”组合：
- **优先**：`fbp + fbc`（对 web 场景非常关键）
- **增强**：`email_sha256` / `phone_sha256`（用户登录/下单后可得，显著提升跨设备/匹配率）
- **辅助**：`client_ip_address + client_user_agent`（常见必填/强建议字段，按官方要求为准）
### 2.3 Meta 能“获取”到哪些外部数据？（澄清）
Meta 分两条线：
- **你从 Meta 拉到的**：投放结构 + 聚合报表（insights：展示、点击、花费、聚合转化等）
- **你回传给 Meta 的**：站内事件（Purchase/AddToCart…）+ 匹配标识符（fbp/fbc/哈希PII…）
> 提权点：Meta 不会把“用户是谁”回给你；你要的“外部数据”是 **campaign/adset/ad 层级的聚合指标**，用于与你站内画像做 join。
### 2.4 Meta 打通闭环的最小工程动作
- **商家侧**：
  - 确保落地页保留 `fbclid`
  - 允许写入一方 cookie（`_fbp/_fbc`）或由你们 SDK 兼容生成
- **你们 SaaS**：
  - 采集：落地页 → 解析 `fbclid` → 写入/读取 `fbp/fbc` → 上报到你们
  - 订单：下单时把 `order_id ↔ anonymous_id/user_id ↔ fbp/fbc` 绑定
  - 回传：用 CAPI 回传 Purchase（带 `event_id` 做去重）
  - 富化：定时拉 insights，把 campaign 维度指标回灌画像/分析库
---
## 3. Google Ads：官方授权机制 + 归因标签 + Enhanced Conversions
参考（官方）：
- `https://developers.google.com/google-ads/api/docs/start`
- `https://developers.google.com/google-ads/api/docs/oauth/overview`
-（增强型转化/Enhanced Conversions 官方入口通常在 Google Ads/Tag/Measurement 文档体系中，落地时请以最新官方页为准）
### 3.1 授权机制（你们最常见的 SaaS 形态）
Google Ads API 通常涉及：
- **Developer Token**：你们应用级别的“开发者资质”
- **OAuth 2.0**：商家授权你们访问其 Google Ads 账户
- **Manager Account (MCC)**（可选）：你们作为管理账号，集中管理多个客户账号（更适合 SaaS）
> 提权点：从产品策略上，建议你们尽早支持“通过 MCC 管理多商家”，否则单店授权与权限维护成本会在规模化后爆炸。
### 3.2 归因标签（Attribution Tags）：Google 这边你到底要沉淀什么？
Google 侧可串联的关键入口标识：
- `gclid`：点击标识（web/传统场景）
- `wbraid` / `gbraid`：移动/隐私/特定投放场景下的点击标识（你们应该一并支持采集与存储）
你们内部“归因标签”建议最小字段：
- `google.click_id`：优先存 `gclid`，否则存 `wbraid/gbraid`（并记录类型）
- `campaign_id` / `ad_group_id` / `keyword_id` / `match_type`（实时意图更稳定）
- `utm_*`（若商家已有）
> 提权点：不要把“search_term（搜索词）”作为实时意图的核心依赖；它受隐私阈值影响、延迟高。用广告组/关键词/匹配类型更稳定。
### 3.3 用户匹配（Enhanced Conversions）怎么用？
Enhanced Conversions 的定位与 Meta Advanced Matching 类似：
- 你在回传转化时附带 **哈希化 PII**（邮箱/手机号/地址等，按官方支持字段）
- 平台用它提升匹配率（尤其跨设备、cookie 受限场景）
你们工程落地建议：
- 只在 **用户已明确同意** 且 **商家可合法使用** 的前提下启用
- 在你们 SDK/后端统一做 **标准化 → SHA-256**（避免商家各自实现造成不一致）
### 3.4 外部数据打通：Google 能给你什么？
- **你从 Google 拉到的**：campaign/adgroup/keyword 维度的聚合指标（展示/点击/花费/转化…）
- **你回传给 Google 的**：离线/在线转化（Conversion Upload）
> 提权点：Google 并不会把“某个 gclid 对应哪个用户”回给你；你要做的是把 gclid 与你自己的 `anonymous_id/order_id` 绑定，然后用报表维度做分析/分群/推荐策略。
---
## 4. TikTok：官方授权机制 + Events API 用户匹配（Advanced Matching 类能力）
参考（官方）：
- `https://developers.tiktok.com/`
- `https://ads.tiktok.com/marketing_api/docs`
-（Events API 官方页通常在 Ads/Marketing API 文档下的 Events/Pixel 章节）
### 4.1 授权机制（Marketing API / 报表拉取）
典型流程：
- 商家在你们后台点击“连接 TikTok” → OAuth → 你们拿到 token
- 你们用 token 拉取 `advertiser_id` 下的 campaign/adgroup/ad 报表与元数据
### 4.2 用户匹配：Events API 里的关键标识符
TikTok 场景下最常见的串联信号：
- `ttclid`：点击标识（落地页 URL 参数）
- `_ttp`：一方 cookie（由 Pixel/SDK 生成或你们 SDK 兼容）
- 哈希 PII：邮箱/手机号（标准化后 SHA-256，需合规）
### 4.3 外部数据打通：TikTok 能给你什么？
- **你从 TikTok 拉到的**：投放结构 + 聚合报表（展示/点击/花费/转化…）
- **你回传给 TikTok 的**：站内关键事件（Purchase/AddToCart…）
---
## 5. Cross-Device（跨设备用户关联）：你们 SaaS 内部的“身份图谱”落地法
### 5.1 身份图谱的节点与边（建议数据模型）
- **节点（ID 类型）**：
  - `anonymous_id`（你们 cookie/device id）
  - `user_id`（商家会员）
  - `email_sha256`、`phone_sha256`
  - `meta.fbp`、`meta.fbc`
  - `tiktok.ttp`
  - `google.click_id`（gclid/wbraid/gbraid）
- **边（关联证据）**：
  - `login`：同一会话中 `anonymous_id ↔ user_id`
  - `checkout`：同一订单 `order_id` 绑定多个标识
  - `platform_match`：回传事件时同一 payload 中出现（fbp+email_sha256 等）
### 5.2 合并策略（先确定性，后概率）
- **确定性合并（MVP 必做）**：
  - 登录/下单/留资触发合并：把历史匿名行为挂到 `user_id`
  - 采用“主键用户（canonical user）”策略：一旦有 `user_id`，以其为主
- **概率性合并（迭代项）**：
  - 设备指纹/行为序列相似度/IP 近似等
  - 仅作为“候选关联”，不要直接影响计费/归因等敏感逻辑
### 5.3 你们与平台跨设备能力的边界
- 平台（Meta/Google/TikTok）拥有自己的跨设备图谱：你无法直接拿到其图谱细节
- 你们能做的是：在合规前提下把更多“可匹配信号”回传 → 平台归因更准 → 你们从报表拿到更可靠的聚合维度
---
## 6. “外部数据打通”的标准 Join 方法（你们数据仓库/画像侧）
### 6.1 两类 Join：实时 vs 离线
- **实时（推荐/分群）**：只依赖你们采集到的入口参数与 click id/一方 cookie
  - 例：用户首次进入就打上 `traffic_source=google_ads`、`g_campaign_id=...`
- **离线（归因分析/成本/ROI）**：用平台报表把 `campaign_id/ad_id/keyword_id` 维度的指标回灌
  - 例：每天把 cost/conv_value 写入 campaign 维度事实表
### 6.2 典型数据表建议
- `event_stream`：站内事件（含 click id/一方 cookie/哈希PII）
- `identity_graph_edges`：ID 关联边（证据、时间、权重）
- `ad_platform_reports_daily`：平台聚合报表（按 tenant + platform + campaign/adgroup/... + date）
- `user_profile`：用户画像（实时标签 + 离线标签）
---
## 7. 合规与安全（必须前置，不然“提权”变“踩雷”）
- **Consent**：把 consent 状态作为事件字段，决定是否写 cookie、是否回传哈希PII、是否用于个性化
- **最小化**：只传/存必要字段；`landing_url/referrer` 参数白名单 + 脱敏
- **哈希规范统一**：标准化（trim、lower、去空格、E164 等）→ SHA-256；避免商家各自实现导致匹配率下降
- **分租户隔离**：token、数据源密钥、identity graph 必须 tenant 隔离（含日志与备份）
---
## 8. 与现有文档的关系（避免重复）
- 全量 S2S 闭环、归因标签字段、端到端案例（更偏“怎么接入平台”）：`docs/全渠道数据整合-广告平台S2S对接手册.md`
- 本文（更偏“为什么这样能匹配、哪些字段/机制能提权匹配率、跨设备怎么做”）：`docs/用户匹配与外部数据打通-平台官方机制提权.md`