ai-saas / saas-search

用户匹配与外部数据打通-平台官方机制提权.md 14 KB

用户匹配与外部数据打通：平台官方机制提权（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

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