From 323a720b91999f92f157f423ec65c781aa36245c Mon Sep 17 00:00:00 2001 From: tangwang Date: Fri, 9 Jan 2026 11:26:27 +0800 Subject: [PATCH] docs --- docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md | 294 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ docs/UA-站内全站埋点数据结构定义.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/个性化.md | 9 --------- docs/blog/全渠道数据整合、外部数据打通/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md | 424 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md | 296 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md | 700 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/proto/user_action.proto | 296 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/全渠道数据整合-广告平台S2S对接手册.md | 409 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/用户匹配与外部数据打通-平台官方机制提权.md | 281 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md | 135 --------------------------------------------------------------------------------------------------------------------------------------- docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md | 136 ---------------------------------------------------------------------------------------------------------------------------------------- docs/竞品参考文档/Nosto-用户数据获取技术方案.md | 198 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ docs/竞品参考文档/prefixbox_api.md | 700 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md | 204 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ 19 files changed, 2833 insertions(+), 2366 deletions(-) delete mode 100644 docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md create mode 100644 docs/UA-站内全站埋点数据结构定义.md delete mode 100644 docs/blog/个性化.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md create mode 100644 docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md create mode 100644 docs/proto/user_action.proto delete mode 100644 docs/全渠道数据整合-广告平台S2S对接手册.md delete mode 100644 docs/用户匹配与外部数据打通-平台官方机制提权.md delete mode 100644 docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md delete mode 100644 docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md delete mode 100644 docs/竞品参考文档/Nosto-用户数据获取技术方案.md delete mode 100644 docs/竞品参考文档/prefixbox_api.md delete mode 100644 docs/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md diff --git a/docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md b/docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md deleted file mode 100644 index e896948..0000000 --- a/docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md +++ /dev/null @@ -1,294 +0,0 @@ -# Shopify 生态：个性化营销/推荐 SaaS 如何获取“外部用户信息”与个性化信号（渠道、方式、数据项、案例） - -> 目标：回答“Shopify 店铺及其个性化营销 SaaS 一般怎么拿到外部用户信息/个性化信息？有哪些渠道、方式、能拿到什么数据？有哪些案例？” -> 结论先行：Shopify 生态里大多数个性化/营销 SaaS 的数据获取是 **“Shopify 第一方业务数据（Admin API/Webhooks） + 站内行为事件（Web Pixels/前端采集） + 外部平台连接（广告/邮件短信/忠诚度/客服/物流等）”** 三路合流，再在 SaaS 内部做身份合并、分群与个性化执行。 - ---- - -## 1. Shopify 生态的数据边界（先把“能/不能”说清楚） - -### 1.1 Shopify 是商家的“业务事实源（System of Record）” - -对个性化营销 SaaS 来说，Shopify 最稳定、最可依赖的数据来自： - -- **商品与库存**：Product / Variant / Collection / Price / Inventory -- **订单与履约**：Order / Line items / Discounts / Refunds / Fulfillment -- **客户与会员**：Customer（邮箱/手机号/地址/营销订阅状态等，视商家收集与合规） -- **店铺配置与渠道**：Sales channel/支付/配送等（通常是辅助） - -这些数据通常是“店内真实发生的事实”，适合做画像、分群、RFM、LTV、复购预测等。 - -### 1.2 “外部用户信息”通常不是 Shopify 直接给，而是靠“连接外部平台”拿 - -你想要的外部信号（广告点击、邮件打开点击、短信互动、社媒广告归因、客服对话、物流轨迹、评论/会员积分等），一般需要： - -- 商家授权第三方 SaaS 连接对应平台（OAuth / API Key / App 安装） -- SaaS 通过平台 API / Webhook 拉取或接收事件 -- 再与 Shopify 的 customer/order 维度做 join - ---- - -## 2. Shopify 侧：营销/个性化 SaaS 获取数据的“主干通道” - -> 这部分是 Shopify 生态里最关键的“取数通道”。典型 SaaS 都会同时使用 2～3 种。 - -### 2.1 Admin API（REST/GraphQL）：批量同步“业务事实” - -**用途**：首次全量同步 + 周期性增量同步（商品、客户、订单、库存…）。 - -- **能拿到的数据（典型）**： - - **Catalog**：商品标题/描述/图片/类目/标签/价格/变体/SKU/库存 - - **Orders**：下单时间、金额、折扣、税费、货币、line items、收货地址（如存在）、退款/取消 - - **Customers**：邮箱/手机号（如收集）、营销订阅状态、默认地址、客户标签（tags）、创建时间、订单数等 -- **工程做法**： - - “首次安装”用 Bulk/分页拉全量 - - “后续变更”主要靠 Webhooks 推送补齐（见下） - -> 注：具体字段/资源会随 Shopify 版本与权限变化；你们在实现时应以 `shopify.dev` 的 Admin API 文档与应用权限为准。 - -### 2.2 Webhooks：实时接收“业务事件” - -**用途**：订单创建/更新、退款、客户更新、库存变化等“事实变化”实时进入你们系统，支撑自动化与实时分群。 - -- **常见事件类别**： - - **订单链路**：create/update/paid/fulfilled/cancelled/refunded（实际 topic 以官方为准） - - **客户链路**：customer create/update、营销订阅状态变化 - - **商品链路**：product/variant/inventory 更新 -- **能拿到的数据**： - - 事件对应对象的“快照”（订单、客户、商品等） - - 事件时间、对象 ID（可用于幂等与去重） -- **典型用法（个性化/营销）**： - - 下单后触发：感谢邮件、交叉销售、评价邀请、会员积分发放 - - 退款后触发：挽回流失/客服介入 - -### 2.3 Web Pixels / Customer Events：采集站内行为（浏览/加购/结账开始） - -**用途**：这是“个性化推荐/行为触发营销”的核心数据源，弥补 Shopify 业务事实对“浏览过程”的缺失。 - -- **能拿到的数据（典型事件）**： - - 页面浏览、商品浏览、加购、开始结账、搜索、支付成功（部分场景） - - 页面/商品/购物车上下文（视事件与权限） -- **工程做法**： - - SaaS 通过 Shopify 的 Pixel/扩展机制注入追踪逻辑 - - 事件发送到 SaaS 的采集 API（你们控制 schema 与幂等） -- **关键约束**： - - 受 **客户隐私/同意管理**影响（见 2.5） - - Safari/Firefox/Chrome 的追踪限制会降低第三方 cookie 能力，所以主流 SaaS 都尽量使用 **第一方 cookie + server-side** 补强 - -### 2.4 Theme App Extension / App Proxy（历史上 ScriptTag）：注入与回传 - -**用途**：当需要在 storefront 上做更深的 UI/逻辑（弹窗、推荐位、表单、A/B）、或需要走你们域名的 server-to-server 通道时使用。 - -- **Theme App Extension**：更“Shopify 原生”的注入方式（替代很多旧式 ScriptTag） -- **App Proxy**：把 `/apps/xxx` 路径代理到你们服务端，常用于： - - 把前端采集的 click id / 匿名 id 在“第一方路径”回传给你们 - - 输出个性化推荐结果（例如 `/apps/reco?context=...`） - -### 2.5 Customer Privacy / Consent：决定“哪些信号能收、能用、能分享” - -**用途**：合规与工程强绑定。你们要把 consent 作为数据管道的开关： - -- **能影响的环节**： - - 是否能写 cookie、是否能触发追踪像素 - - 是否能把哈希邮箱/手机号用于广告平台匹配（Enhanced/Advanced Matching） - - 是否允许把站内行为用于个性化（某些地区必须 opt-in） - ---- - -## 3. “外部用户信息/个性化信号”的主要渠道（Shopify 生态常见做法） - -下面按渠道拆解“怎么接、能拿到哪些数据、能做哪些个性化”。 - -### 3.1 广告/社交流量平台（Meta / Google / TikTok 等） - -**目的**：把“外部点击/触达”与“站内行为/订单”串起来（归因 + 人群 + 个性化）。 - -- **接入方式**： - - **Shopify Channel App**（Meta/Google/TikTok 官方渠道应用）：目录同步、像素/事件配置、广告管理入口 - - **SaaS 自己对接广告平台 API**（OAuth + CAPI/Events API/Conversion Upload + 报表拉取） -- **你能拿到的数据**（对个性化 SaaS 最有用的）： - - **click id / 入口参数**：`fbclid`、`ttclid`、`gclid/wbraid/gbraid`、UTM - - **归因维度（聚合）**：campaign/adgroup/ad/keyword、cost、impressions、clicks、conversions（报表拉取） - - **匹配增强**：哈希邮箱/手机号（用户下单/登录后得到）用于提升归因与跨设备匹配 -- **典型用法**： - - 实时推荐：首次进入时就根据 `utm_campaign/adgroup` 打意图标签（“跑鞋广告组用户”） - - 分群：把“来自某 campaign 且购买过某品类”的客户形成高价值人群，回传投放 - -> 你们之前的广告平台对接与用户匹配细节可参考：`docs/用户匹配与外部数据打通-平台官方机制提权.md` - -### 3.2 邮件/短信（Klaviyo / Omnisend / Attentive 等） - -**目的**：拿到“用户沟通互动”这一类外部信号，并把 Shopify 订单/行为用于触发自动化。 - -- **接入方式**： - - Shopify App 安装后，SaaS 通过 Admin API/Webhooks 同步客户与订单 - - 通过 Web Pixel/前端采集拿到浏览/加购/结账开始 - - 邮件/短信平台回传互动：发送、送达、打开、点击、退订、投诉等（平台 API/Webhook） -- **你能拿到的数据**： - - **身份**：email/phone（以及订阅状态） - - **行为**：viewed product / added to cart / checkout started / placed order（站内事件） - - **触达效果**：open/click/attributed revenue（沟通侧事件） -- **典型用法**： - - “弃购”与“浏览未购”自动化 - - 基于 LTV/RFM 的分层触达（VIP、沉睡唤醒、首单转化） - -**案例：Klaviyo（典型数据链路）** - -- **Shopify → Klaviyo**：客户、订单、商品目录、以及站内行为（浏览/加购/结账开始） -- **Klaviyo → Shopify/商家**：邮件/短信互动、分群结果、归因收入报表 - -> 公开资料入口：可从 Klaviyo developer docs 与其 Shopify integration 文档进一步细化字段（建议你们实现时按其 webhook/event schema 对齐）。 - -### 3.3 会员/忠诚度/评价（Yotpo / LoyaltyLion / Judge.me 等） - -**目的**：获取“口碑/忠诚度”信号，辅助个性化（例如 VIP 专属、评价驱动推荐）。 - -- **接入方式**： - - Shopify Webhooks：订单完成触发评价邀请/积分 - - SaaS 自身 API：评价提交、积分变动、会员等级变动（回传到你们或你们对接它） -- **能拿到的数据**： - - **评价**：评分、评论文本、图片、商品 ID、时间 - - **忠诚度**：积分、等级、任务完成、兑换记录 - - **触达互动**：评价邮件打开/点击、SMS 互动（视产品） -- **个性化用法**： - - 推荐理由：展示“同等级用户喜欢” - - 权益个性化：VIP 只看 VIP 价、专属礼包 - -**案例：Yotpo（典型信号）** - -- Reviews/UGC：商品级口碑信号 -- Loyalty：用户级“忠诚度标签” -- SMS/Email：触达互动信号 - -### 3.4 客服/工单/在线聊天（Gorgias / Zendesk / Reamaze 等） - -**目的**：把“服务侧信号”纳入画像（投诉、退换、咨询意图），做更稳健的个性化。 - -- **接入方式**： - - 客服系统 API/Webhook（ticket created/updated, tags, CSAT） - - 与 Shopify 订单/客户 join（通常靠 email/phone/order_id） -- **能拿到的数据**： - - 工单类型、标签、优先级、解决时长、满意度 - - 对话文本（注意隐私与脱敏） -- **个性化用法**： - - 对高投诉用户避免强推销，先服务后营销 - - 退货风险用户推荐更稳妥的商品/尺码指引 - -### 3.5 物流/履约/退换货（AfterShip / Loop Returns 等） - -**目的**：让营销/推荐“知道物流与退换状态”，避免误触达。 - -- **接入方式**： - - 物流/退货平台 API/Webhook（shipment update, delivered, return initiated, return received） - - Shopify Fulfillment/Refund Webhooks 作为补充 -- **能拿到的数据**： - - 运输状态、妥投时间、异常（延误/丢件） - - 退货原因、退货商品、退款金额 -- **个性化用法**： - - “已签收 + 7 天”触发评价/复购推荐 - - 退货原因驱动推荐（尺码偏小 → 推荐更合适尺码/替代款） - -### 3.6 CDP/数据管道（Segment / mParticle / RudderStack 等） - -**目的**：把多触点事件（站内、App、广告、邮件短信、客服）统一成事件流，再分发给各 SaaS/仓库。 - -- **接入方式**： - - Shopify 站内事件 → CDP - - Shopify 订单/客户 → 数据仓库/ETL - - 外部平台事件 → CDP -- **能拿到的数据**： - - 统一事件流（标准化 schema） - - 更强的路由与治理能力（去重、版本、权限） - -> 对你们要做“电商个性化引擎 SaaS”而言，CDP 是“生态对接加速器”，但不是必需前置。很多 SaaS 是自己做事件总线（Kafka）+ connector。 - -### 3.7 Shopify Audiences（生态里很特殊的一条“外部能力”） - -**定位**：偏“广告获客/人群投放”的能力；它的关键价值是“用 Shopify 网络/数据能力帮助生成高意图受众”，而不是把原始用户数据给第三方。 - -- **你能得到的**：可用于投放平台的“受众包/受众类型”（面向 Meta 等，具体以官方为准） -- **你通常拿不到的**：可反推出个体用户身份的原始明细（更偏隐私保护） - ---- - -## 4. 个性化营销 SaaS 在 Shopify 上的典型落地架构（你们可直接借鉴） - -### 4.1 三条数据管道 - -- **事实管道（Admin API + Webhooks）**：客户/订单/商品/库存 -- **行为管道（Web Pixels/前端采集）**：浏览/加购/结账开始/搜索 -- **外部信号管道（平台 API/Webhooks）**：广告、邮件短信、忠诚度、客服、物流 - -### 4.2 统一身份（最常见 join key） - -- **确定性主键**：email、phone、Shopify customer id、order id -- **匿名阶段**：first-party cookie / `anonymous_id` -- **广告归因**：click id（fbclid/ttclid/gclid/wbraid/gbraid）+ 哈希 PII（合规后） - ---- - -## 5. 典型案例：个性化/推荐 SaaS 在 Shopify 上怎么“拿数并生效” - -### 5.1 Rebuy / 同类站内推荐 - -- **输入**： - - Shopify 商品目录/库存/价格（Admin API） - - 订单与历史购买（Webhooks/同步） - - 实时行为（浏览/加购/结账开始：Web Pixels/前端采集） -- **输出**： - - 推荐位渲染（Theme App Extension / App Proxy） - - A/B 测试与归因（自身埋点 + Shopify 订单回流） - -### 5.2 Nosto / 同类全渠道个性化 - -- **输入**： - - Shopify 业务事实（产品/订单/客户） - - 站内行为（Pixel/事件） - - 广告/邮件短信等外部平台对接（S2S + 报表） -- **输出**： - - 站内推荐、个性化排序、受众分群与回传投放 - -### 5.3 Klaviyo / 同类营销自动化 - -- **输入**： - - Shopify 客户/订单/目录 - - 站内行为事件 - - 邮件/短信互动事件（打开/点击/退订） -- **输出**： - - 自动化流程（welcome、abandon cart、browse abandon、post-purchase） - - 高价值分群（VIP、沉睡、复购） - -### 5.4 Yotpo / 同类评价与忠诚度 - -- **输入**： - - 订单触发（发起评价邀请、积分发放） - - 评价/UGC/忠诚度事件 -- **输出**： - - 商品口碑展示、VIP 权益、复购激励 - ---- - -## 6. 给你们做“个性化推进引擎 SaaS”的落地建议（Shopify 生态优先级） - -### 6.1 MVP（最小闭环） - -- **Shopify Admin API + Webhooks**：同步商品/客户/订单 -- **Web Pixels/前端采集**：补齐浏览/加购/结账开始等行为 -- **一个外部平台连接**：优先 Meta 或 Google（看商家投放结构） -- **身份合并**：anonymous → email/phone/customer_id 的确定性合并 - -### 6.2 增强（提权匹配与外部闭环） - -- 广告平台：CAPI/Events API/Conversion Upload + 报表拉取 -- 邮件短信：对接 Klaviyo/Omnisend/Attentive 的互动事件（open/click） -- 物流/退换：把“已签收/退货原因”纳入策略 - ---- - -## 7. 参考入口（建议你们实现时以官方文档为准） - -- Shopify Developer Docs：`https://shopify.dev/` -- Shopify Help Center（Audiences/隐私/营销报告等）：`https://help.shopify.com/` -- Shopify Audiences（受众类型说明等，help center 页面为准）：`https://help.shopify.com/` - - diff --git a/docs/UA-站内全站埋点数据结构定义.md b/docs/UA-站内全站埋点数据结构定义.md new file mode 100644 index 0000000..03df517 --- /dev/null +++ b/docs/UA-站内全站埋点数据结构定义.md @@ -0,0 +1,105 @@ +# UA 站内全站埋点数据结构定义（推荐/搜索/画像统一口径） + +本文档用于定义站内全量行为采集（基于“全站埋点采集”，可落地到神策 JS SDK 二次开发），覆盖推荐、搜索、画像、转化分析等核心场景。 + +## 1. 目标与约束 + +- **目标**：用一套统一事件模型覆盖全站行为（Pageview / Exposure / Click / View Product / Add to Cart / Purchase / Search&Filtering / Cart&Checkout）。 +- **约束**：事件需要能在“推荐/搜索请求”与“曝光-点击-加购”等链路上串联；同时需要能表达购物车/结账阶段的状态快照，用于搭配、互补、凑单、替代品推荐。 + +## 2. 关键设计原则 + +- **统一事件骨架**：所有事件共享同一套顶层字段（用户标识、时间、页面、trace、设备、扩展字段），业务差异放到 `event`（oneof）里。 +- **可串联**：用 `trace_id` 串联一次搜索/推荐请求与后续点击、加购、详情浏览等行为；用 `session_id` 串联同一次访问会话。 +- **可回放/可训练**：曝光事件尽量携带曝光商品列表、位置、模块；购物车/结账事件携带快照（items + 国家/币种/价格等）。 +- **停留时长口径一致**：对 `page_view`/`view_item` 统一给出 `dwell_time_ms` 的采集口径与上报方式。 + +## 3. 顶层事件模型（概念） + +每条 UA 事件为一个 `UserActionEvent`，包含： + +- **identity**：tenant / user / anonymous / device / cookie +- **time**：事件发生时间（毫秒时间戳） +- **page**：页面类型、URL、来源、模块位置信息 +- **trace**：`trace_id`、`session_id`、实验信息 +- **device**：OS / UA / viewport 等 +- **event**：具体业务事件（page_view、exposure、click、view_item、search、filter、cart、checkout、purchase…） +- **extra**：业务扩展 KV + +> proto 草案见 `docs/proto/user_action.proto`（本次补充文件）。 + +## 4. 核心字段说明 + +### 4.1 标识体系（强烈建议） + +- **tenant_id**：租户/店铺/商家维度的隔离主键。 +- **user_id**：登录用户 ID（未登录可为空）。 +- **anonymous_id**：匿名用户 ID（建议 Cookie 级别稳定，登录后可与 user_id 做归因合并）。 +- **device_id**：设备指纹（可选；Web 端更推荐 anonymous_id + cookie_id）。 +- **cookie_id**：首次访问生成的持久化 Cookie ID（与 anonymous_id 可以一致，也可分开）。 + +### 4.2 trace_id（最重要） + +**定义**：串联一次“搜索/推荐请求（曝光）”与后续点击、详情、加购等行为的请求级会话 ID，同时用于串联内部技术模块（召回/排序/重排等子模块日志）。 + +**规则建议**： + +- **新搜索/新推荐刷新**：生成新的 `trace_id`。 +- **搜索翻页**：沿用原 `trace_id`，用 `page_number` 区分页（见 `SearchEvent`）。 +- **曝光 → 点击/详情/加购**：沿用产生曝光的 `trace_id`，用于表达“该转化源自哪一次曝光/哪一次请求”。 +- **购买/支付**：如果链路被购物车长时间阻隔，串联成本高，可不强制要求延续 `trace_id`；但建议在 `PurchaseEvent.attribution_trace_id` 上尽力保留“主要来源”的 trace（若可得）。 + +### 4.3 停留时长（dwell_time_ms） + +**适用事件**： + +- `PageViewEvent`：用户在该页面的停留时长 +- `ViewItemEvent`：用户在详情页/商品内容上的停留时长（可与 pageview 相同，也可更精细） + +**采集口径建议（Web）**： + +- 在 `pagehide` / `beforeunload` / SPA 路由切换时计算当前页面停留：`now - enter_time`。 +- 若页面进入后立即产生 `page_view`，则可在离开页面时补发一条 `page_view_end`（或在同一条事件里填充 `dwell_time_ms`，需要延迟上报）。 +- 对详情页：可按“进入详情页到离开详情页”计算；若停留时长无法计算，允许不上报或置 0，但需要在文档/ETL 中区分“缺失 vs 真实 0”。 + +## 5. 必须覆盖的事件清单（推荐） + +- **Pageview** + - 分类页、活动页、列表页、首页、店铺页、购物车页、结账页等 + - *最好携带该页面曝光的商品列表*（见 `ExposureEvent`，或在 `PageViewEvent.exposed_items` 携带“本页首屏/本次渲染”曝光） +- **Exposure / Click** + - 列表/推荐位曝光与点击（必须包含 position / module_id / item） +- **View product（详情页浏览）** + - 包含 `dwell_time_ms` +- **Add to cart** + - 商品信息 + 数量 + 价格（若可得）+ 当前 cart 快照（若可得） +- **Purchase** + - 订单信息（order_id / currency / total）+ 购买 items +- **On-site Search & Filtering** + - 搜索词、建议词、排序、筛选条件（结构化，避免仅 JSON 字符串） + - 搜索结果曝光/点击建议归入 Exposure/Click，但必须携带 `search_context` +- **Cart Logic / Checkout 状态** + - `cart_snapshot`：购物车当前 items 及属性（qty、price、category、brand…） + - `checkout`：shipping_country、step、payment_method（如可得） + +## 6. 落地建议（神策 JS SDK 二次开发） + +- **事件名**：建议统一用一个事件名（如 `ua_event`），将 `action_type`（主类型）+ `event_id`（子类型，可选）作为属性；或按神策习惯拆分事件名，但必须保证字段一致。 +- **批量上报**：曝光事件可批量（一屏/一次渲染一次上报）以降低量级；点击/加购/购买等强转化事件单条实时上报。 +- **字段扩展**：放入 `extra.debug_info`，严禁在顶层无限加字段造成版本失控。 + +## 7. proto 草案 + +见 `docs/proto/user_action.proto`。 + +### 7.1 枚举命名说明（避免 proto 枚举值冲突） + +为兼容较旧版本 `protoc`（枚举值采用 package 级作用域），本 proto 中枚举值都带前缀： + +- **ActionType**：`ACTION_TYPE_*`（如 `ACTION_TYPE_PAGEVIEW`） +- **EventId**：`EVENT_ID_*`（如 `EVENT_ID_ADD_TO_CART`） +- **PageType**：`PAGE_TYPE_*` +- **SortType**：`SORT_TYPE_*` +- **CheckoutStep**：`CHECKOUT_STEP_*` + + diff --git a/docs/blog/个性化.md b/docs/blog/个性化.md deleted file mode 100644 index 0cadcbb..0000000 --- a/docs/blog/个性化.md +++ /dev/null @@ -1,9 +0,0 @@ - -| 数据类型 | 采集方式 | 应用场景 | 示例 | -| ---------- | ----------------- | ---------- | -------------------------------------- | -| **流量来源** | UTM参数、referrer解析 | 欢迎页差异化展示 | Instagram用户看到"网红同款"，Facebook用户看到"好友购买" | -| **页面行为** | 前端埋点、SDK | 实时意图判断 | 商品页停留>30秒→触发"库存紧张"提示 | -| **交易数据** | 订单API、Webhook | RFM分群、复购预测 | 近30天购买3次+客单价>\$100→标记"高价值用户" | -| **用户属性** | 注册表单、CRM导入 | 精准分群 | 年龄>35岁+女性→推荐抗衰老护肤品 | -| **设备/环境** | User-Agent、IP地理定位 | 体验适配 | iOS用户→App下载引导，安卓用户→Google Pay支付 | -| **邮箱/手机号** | 登录、订阅（需授权） | 跨渠道唤醒 | 弃购后2小时发邮件，展示"最近浏览"抽屉 | diff --git a/docs/blog/全渠道数据整合、外部数据打通/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md b/docs/blog/全渠道数据整合、外部数据打通/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md new file mode 100644 index 0000000..a70a5f2 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md @@ -0,0 +1,304 @@ +# Shopify 生态：个性化营销/推荐 SaaS 如何获取“外部用户信息”与个性化信号（渠道、方式、数据项、案例） + +> 目标：回答“Shopify 店铺及其个性化营销 SaaS 一般怎么拿到外部用户信息/个性化信息？有哪些渠道、方式、能拿到什么数据？有哪些案例？” +> 结论先行：Shopify 生态里大多数个性化/营销 SaaS 的数据获取是 **“Shopify 第一方业务数据（Admin API/Webhooks） + 站内行为事件（Web Pixels/前端采集） + 外部平台连接（广告/邮件短信/忠诚度/客服/物流等）”** 三路合流，再在 SaaS 内部做身份合并、分群与个性化执行。 + +--- + +## 1. Shopify 生态的数据边界（先把“能/不能”说清楚） + +### 1.1 Shopify 是商家的“业务事实源（System of Record）” + +对个性化营销 SaaS 来说，Shopify 最稳定、最可依赖的数据来自： + +- **商品与库存**：Product / Variant / Collection / Price / Inventory +- **订单与履约**：Order / Line items / Discounts / Refunds / Fulfillment +- **客户与会员**：Customer（邮箱/手机号/地址/营销订阅状态等，视商家收集与合规） +- **店铺配置与渠道**：Sales channel/支付/配送等（通常是辅助） + +这些数据通常是“店内真实发生的事实”，适合做画像、分群、RFM、LTV、复购预测等。 + +### 1.2 “外部用户信息”通常不是 Shopify 直接给，而是靠“连接外部平台”拿 + +你想要的外部信号（广告点击、邮件打开点击、短信互动、社媒广告归因、客服对话、物流轨迹、评论/会员积分等），一般需要： + +- 商家授权第三方 SaaS 连接对应平台（OAuth / API Key / App 安装） +- SaaS 通过平台 API / Webhook 拉取或接收事件 +- 再与 Shopify 的 customer/order 维度做 join + +--- + +## 2. Shopify 侧：营销/个性化 SaaS 获取数据的“主干通道” + +> 这部分是 Shopify 生态里最关键的“取数通道”。典型 SaaS 都会同时使用 2～3 种。 + +### 2.1 Admin API（REST/GraphQL）：批量同步“业务事实” + +**用途**：首次全量同步 + 周期性增量同步（商品、客户、订单、库存…）。 + +- **能拿到的数据（典型）**： + - **Catalog**：商品标题/描述/图片/类目/标签/价格/变体/SKU/库存 + - **Orders**：下单时间、金额、折扣、税费、货币、line items、收货地址（如存在）、退款/取消 + - **Customers**：邮箱/手机号（如收集）、营销订阅状态、默认地址、客户标签（tags）、创建时间、订单数等 +- **工程做法**： + - “首次安装”用 Bulk/分页拉全量 + - “后续变更”主要靠 Webhooks 推送补齐（见下） + +> 注：具体字段/资源会随 Shopify 版本与权限变化；你们在实现时应以 `shopify.dev` 的 Admin API 文档与应用权限为准。 + +### 2.2 Webhooks：实时接收“业务事件” + +**用途**：订单创建/更新、退款、客户更新、库存变化等“事实变化”实时进入你们系统，支撑自动化与实时分群。 + +- **常见事件类别**： + - **订单链路**：create/update/paid/fulfilled/cancelled/refunded（实际 topic 以官方为准） + - **客户链路**：customer create/update、营销订阅状态变化 + - **商品链路**：product/variant/inventory 更新 +- **能拿到的数据**： + - 事件对应对象的“快照”（订单、客户、商品等） + - 事件时间、对象 ID（可用于幂等与去重） +- **典型用法（个性化/营销）**： + - 下单后触发：感谢邮件、交叉销售、评价邀请、会员积分发放 + - 退款后触发：挽回流失/客服介入 + +### 2.3 Web Pixels / Customer Events：采集站内行为（浏览/加购/结账开始） + +**用途**：这是“个性化推荐/行为触发营销”的核心数据源，弥补 Shopify 业务事实对“浏览过程”的缺失。 + +- **能拿到的数据（典型事件）**： + - 页面浏览、商品浏览、加购、开始结账、搜索、支付成功（部分场景） + - 页面/商品/购物车上下文（视事件与权限） +- **工程做法**： + - SaaS 通过 Shopify 的 Pixel/扩展机制注入追踪逻辑 + - 事件发送到 SaaS 的采集 API（你们控制 schema 与幂等） +- **关键约束**： + - 受 **客户隐私/同意管理**影响（见 2.5） + - Safari/Firefox/Chrome 的追踪限制会降低第三方 cookie 能力，所以主流 SaaS 都尽量使用 **第一方 cookie + server-side** 补强 + +### 2.4 Theme App Extension / App Proxy（历史上 ScriptTag）：注入与回传 + +**用途**：当需要在 storefront 上做更深的 UI/逻辑（弹窗、推荐位、表单、A/B）、或需要走你们域名的 server-to-server 通道时使用。 + +- **Theme App Extension**：更“Shopify 原生”的注入方式（替代很多旧式 ScriptTag） +- **App Proxy**：把 `/apps/xxx` 路径代理到你们服务端，常用于： + - 把前端采集的 click id / 匿名 id 在“第一方路径”回传给你们 + - 输出个性化推荐结果（例如 `/apps/reco?context=...`） + +### 2.5 Customer Privacy / Consent：决定“哪些信号能收、能用、能分享” + +**用途**：合规与工程强绑定。你们要把 consent 作为数据管道的开关： + +- **能影响的环节**： + - 是否能写 cookie、是否能触发追踪像素 + - 是否能把哈希邮箱/手机号用于广告平台匹配（Enhanced/Advanced Matching） + - 是否允许把站内行为用于个性化（某些地区必须 opt-in） + +--- + +## 3. “外部用户信息/个性化信号”的主要渠道（Shopify 生态常见做法） + +下面按渠道拆解“怎么接、能拿到哪些数据、能做哪些个性化”。 + +### 3.1 广告/社交流量平台（Meta / Google / TikTok 等） + +**目的**：把“外部点击/触达”与“站内行为/订单”串起来（归因 + 人群 + 个性化）。 + +- **接入方式**： + - **Shopify Channel App**（Meta/Google/TikTok 官方渠道应用）：目录同步、像素/事件配置、广告管理入口 + - **SaaS 自己对接广告平台 API**（OAuth + CAPI/Events API/Conversion Upload + 报表拉取） +- **你能拿到的数据**（对个性化 SaaS 最有用的）： + - **click id / 入口参数**：`fbclid`、`ttclid`、`gclid/wbraid/gbraid`、UTM + - **归因维度（聚合）**：campaign/adgroup/ad/keyword、cost、impressions、clicks、conversions（报表拉取） + - **匹配增强**：哈希邮箱/手机号（用户下单/登录后得到）用于提升归因与跨设备匹配 +- **典型用法**： + - 实时推荐：首次进入时就根据 `utm_campaign/adgroup` 打意图标签（“跑鞋广告组用户”） + - 分群：把“来自某 campaign 且购买过某品类”的客户形成高价值人群，回传投放 + +> 你们之前的广告平台对接与用户匹配细节可参考：`docs/用户匹配与外部数据打通-平台官方机制提权.md` + +### 3.2 邮件/短信（Klaviyo / Omnisend / Attentive 等） + +**目的**：拿到“用户沟通互动”这一类外部信号，并把 Shopify 订单/行为用于触发自动化。 + +- **接入方式**： + - Shopify App 安装后，SaaS 通过 Admin API/Webhooks 同步客户与订单 + - 通过 Web Pixel/前端采集拿到浏览/加购/结账开始 + - 邮件/短信平台回传互动：发送、送达、打开、点击、退订、投诉等（平台 API/Webhook） +- **你能拿到的数据**： + - **身份**：email/phone（以及订阅状态） + - **行为**：viewed product / added to cart / checkout started / placed order（站内事件） + - **触达效果**：open/click/attributed revenue（沟通侧事件） +- **典型用法**： + - “弃购”与“浏览未购”自动化 + - 基于 LTV/RFM 的分层触达（VIP、沉睡唤醒、首单转化） + +**案例：Klaviyo（典型数据链路）** + +- **Shopify → Klaviyo**：客户、订单、商品目录、以及站内行为（浏览/加购/结账开始） +- **Klaviyo → Shopify/商家**：邮件/短信互动、分群结果、归因收入报表 + +> 公开资料入口：可从 Klaviyo developer docs 与其 Shopify integration 文档进一步细化字段（建议你们实现时按其 webhook/event schema 对齐）。 + +### 3.3 会员/忠诚度/评价（Yotpo / LoyaltyLion / Judge.me 等） + +**目的**：获取“口碑/忠诚度”信号，辅助个性化（例如 VIP 专属、评价驱动推荐）。 + +- **接入方式**： + - Shopify Webhooks：订单完成触发评价邀请/积分 + - SaaS 自身 API：评价提交、积分变动、会员等级变动（回传到你们或你们对接它） +- **能拿到的数据**： + - **评价**：评分、评论文本、图片、商品 ID、时间 + - **忠诚度**：积分、等级、任务完成、兑换记录 + - **触达互动**：评价邮件打开/点击、SMS 互动（视产品） +- **个性化用法**： + - 推荐理由：展示“同等级用户喜欢” + - 权益个性化：VIP 只看 VIP 价、专属礼包 + +**案例：Yotpo（典型信号）** + +- Reviews/UGC：商品级口碑信号 +- Loyalty：用户级“忠诚度标签” +- SMS/Email：触达互动信号 + +### 3.4 客服/工单/在线聊天（Gorgias / Zendesk / Reamaze 等） + +**目的**：把“服务侧信号”纳入画像（投诉、退换、咨询意图），做更稳健的个性化。 + +- **接入方式**： + - 客服系统 API/Webhook（ticket created/updated, tags, CSAT） + - 与 Shopify 订单/客户 join（通常靠 email/phone/order_id） +- **能拿到的数据**： + - 工单类型、标签、优先级、解决时长、满意度 + - 对话文本（注意隐私与脱敏） +- **个性化用法**： + - 对高投诉用户避免强推销，先服务后营销 + - 退货风险用户推荐更稳妥的商品/尺码指引 + +### 3.5 物流/履约/退换货（AfterShip / Loop Returns 等） + +**目的**：让营销/推荐“知道物流与退换状态”，避免误触达。 + +- **接入方式**： + - 物流/退货平台 API/Webhook（shipment update, delivered, return initiated, return received） + - Shopify Fulfillment/Refund Webhooks 作为补充 +- **能拿到的数据**： + - 运输状态、妥投时间、异常（延误/丢件） + - 退货原因、退货商品、退款金额 +- **个性化用法**： + - “已签收 + 7 天”触发评价/复购推荐 + - 退货原因驱动推荐（尺码偏小 → 推荐更合适尺码/替代款） + +### 3.6 CDP/数据管道（Segment / mParticle / RudderStack 等） + +**目的**：把多触点事件（站内、App、广告、邮件短信、客服）统一成事件流，再分发给各 SaaS/仓库。 + +- **接入方式**： + - Shopify 站内事件 → CDP + - Shopify 订单/客户 → 数据仓库/ETL + - 外部平台事件 → CDP +- **能拿到的数据**： + - 统一事件流（标准化 schema） + - 更强的路由与治理能力（去重、版本、权限） + +> 对你们要做“电商个性化引擎 SaaS”而言，CDP 是“生态对接加速器”，但不是必需前置。很多 SaaS 是自己做事件总线（Kafka）+ connector。 + +### 3.7 Shopify Audiences（生态里很特殊的一条“外部能力”） + +**定位**：偏“广告获客/人群投放”的能力；它的关键价值是“用 Shopify 网络/数据能力帮助生成高意图受众”，而不是把原始用户数据给第三方。 + +- **你能得到的**：可用于投放平台的“受众包/受众类型”（面向 Meta 等，具体以官方为准） +- **你通常拿不到的**：可反推出个体用户身份的原始明细（更偏隐私保护） + +--- + +## 4. 个性化营销 SaaS 在 Shopify 上的典型落地架构（你们可直接借鉴） + +### 4.1 三条数据管道 + +- **事实管道（Admin API + Webhooks）**：客户/订单/商品/库存 +- **行为管道（Web Pixels/前端采集）**：浏览/加购/结账开始/搜索 +- **外部信号管道（平台 API/Webhooks）**：广告、邮件短信、忠诚度、客服、物流 + +### 4.2 统一身份（最常见 join key） + +- **确定性主键**：email、phone、Shopify customer id、order id +- **匿名阶段**：first-party cookie / `anonymous_id` +- **广告归因**：click id（fbclid/ttclid/gclid/wbraid/gbraid）+ 哈希 PII（合规后） + +--- + +## 5. 典型案例：个性化/推荐 SaaS 在 Shopify 上怎么“拿数并生效” + +### 5.1 Rebuy / 同类站内推荐 + +- **输入**： + - Shopify 商品目录/库存/价格（Admin API） + - 订单与历史购买（Webhooks/同步） + - 实时行为（浏览/加购/结账开始：Web Pixels/前端采集） +- **输出**： + - 推荐位渲染（Theme App Extension / App Proxy） + - A/B 测试与归因（自身埋点 + Shopify 订单回流） + +### 5.2 Nosto / 同类全渠道个性化 + +- **输入**： + - Shopify 业务事实（产品/订单/客户） + - 站内行为（Pixel/事件） + - 广告/邮件短信等外部平台对接（S2S + 报表） +- **输出**： + - 站内推荐、个性化排序、受众分群与回传投放 + +### 5.3 Klaviyo / 同类营销自动化 + +- **输入**： + - Shopify 客户/订单/目录 + - 站内行为事件 + - 邮件/短信互动事件（打开/点击/退订） +- **输出**： + - 自动化流程（welcome、abandon cart、browse abandon、post-purchase） + - 高价值分群（VIP、沉睡、复购） + +### 5.4 Yotpo / 同类评价与忠诚度 + +- **输入**： + - 订单触发（发起评价邀请、积分发放） + - 评价/UGC/忠诚度事件 +- **输出**： + - 商品口碑展示、VIP 权益、复购激励 + +--- + +## 6. 给你们做“个性化推进引擎 SaaS”的落地建议（Shopify 生态优先级） + +### 6.1 MVP（最小闭环） + +- **Shopify Admin API + Webhooks**：同步商品/客户/订单 +- **Web Pixels/前端采集**：补齐浏览/加购/结账开始等行为 +- **一个外部平台连接**：优先 Meta 或 Google（看商家投放结构） +- **身份合并**：anonymous → email/phone/customer_id 的确定性合并 + +### 6.2 增强（提权匹配与外部闭环） + +- 广告平台：CAPI/Events API/Conversion Upload + 报表拉取 +- 邮件短信：对接 Klaviyo/Omnisend/Attentive 的互动事件（open/click） +- 物流/退换：把“已签收/退货原因”纳入策略 + +--- + +## 7. 参考入口（建议你们实现时以官方文档为准） + +- Shopify Developer Docs：`https://shopify.dev/` +- Shopify Help Center（Audiences/隐私/营销报告等）：`https://help.shopify.com/` +- Shopify Audiences（受众类型说明等，help center 页面为准）：`https://help.shopify.com/` + +### 7.1 关联平台（广告/社交）官方入口 + +- **Meta / Facebook** + - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/) + - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/) +- **Google** + - [Google Ads API（Start）](https://developers.google.com/google-ads/api/docs/start) +- **TikTok** + - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs) + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md b/docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md new file mode 100644 index 0000000..0c36e57 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md @@ -0,0 +1,424 @@ +# 全渠道数据整合：广告/社交平台 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` 做脱敏与参数白名单 + +--- + +## 9. 参考链接（官方入口） + +- **Meta / Facebook** + - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/) + - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/) + - [Facebook Login（OAuth 手动流程）](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) +- **Google** + - [Google Ads API（Start）](https://developers.google.com/google-ads/api/docs/start) + - [Google Ads API OAuth（Overview）](https://developers.google.com/google-ads/api/docs/oauth/overview) +- **TikTok** + - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs) + - [TikTok Events API（文档入口）](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106) + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md b/docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md new file mode 100644 index 0000000..6847437 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md @@ -0,0 +1,296 @@ +# 用户匹配与外部数据打通：平台官方机制提权（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. 参考链接（官方入口） + +- **Meta / Facebook** + - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/) + - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/) + - [Facebook Login（OAuth 手动流程）](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) +- **Google** + - [Google Ads API（Start）](https://developers.google.com/google-ads/api/docs/start) + - [Google Ads API OAuth（Overview）](https://developers.google.com/google-ads/api/docs/oauth/overview) +- **TikTok** + - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs) + - [TikTok Events API（文档入口）](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106) + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md new file mode 100644 index 0000000..85fe320 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md @@ -0,0 +1,147 @@ +# Bloomreach：用户数据获取技术方案（拆解版：Engagement / Discovery） + +> 目标：拆解 Bloomreach 在“用户数据获取/统一/激活”的技术路径，覆盖 Bloomreach Engagement（原 Exponea，偏 CDP+营销自动化）与 Bloomreach Discovery（偏搜索/商品发现）。 +> +> 说明：Bloomreach 的开发者文档体系较大，且部分内容面向客户/合作伙伴账号。本文以公开资料与行业通用实现方式做结构化提炼；字段/端点级细节请以你们实际拿到的 Bloomreach 官方文档与 PoC 验证为准。 + +--- + +## 1. Bloomreach 的“取数目标”分两条产品线 + +### 1.1 Engagement（CDP / Marketing Automation） + +**核心目标**：把多渠道事件与用户属性汇总为 Customer 360，并在邮件/短信/推送/站内等渠道做实时触达与分群。 + +### 1.2 Discovery（Search / Merchandising） + +**核心目标**：让搜索/类目页/推荐能基于： + +- 高质量商品目录 +- 用户行为与查询意图（站内搜索词、点击、加购、购买） + +做排序与推荐优化。 + +--- + +## 2. 数据获取的 4 条主通道（Bloomreach 常见架构） + +### 2.1 Web 事件采集（JS SDK / Tag） + +**用途**：采集站内行为（浏览、点击、搜索、加购、结账开始等），并生成匿名 ID / 会话 ID。 + +**你能获得的数据类型**： + +- 页面/商品/类目上下文（URL、product_id、category、price 等） +- 行为事件序列（view → add_to_cart → purchase） +- 会话/设备信号（device、browser、language、geo 近似等） + +### 2.2 Mobile 事件采集（iOS/Android SDK，可选） + +**用途**：App 内事件与身份（device id / login id）进入同一用户画像，用于跨设备与多渠道触达。 + +### 2.3 服务端 S2S 事件与属性导入（Events API / Attributes Import） + +**用途**： + +- 订单支付、退款、取消等“最终事实”由服务端回传，保证一致性 +- CRM/会员/线下交易等属性导入，丰富 Customer 360 + +**典型字段（你们实现时建议对齐）**： + +- `customer_id` / `email_sha256` / `phone_sha256` +- `event_name`（purchase/refund/loyalty_level_changed…） +- `event_time` +- `order_id`（幂等） +- `items[]`（sku/qty/price/category） +- `consent`（是否允许营销/广告/分析） + +### 2.4 商品目录/内容目录导入（Feed / Connector） + +**Engagement 视角**： + +- 把 catalog 作为“推荐与模板渲染”的素材库（邮件/站内推荐等） + +**Discovery 视角**： + +- catalog 是搜索与排序的基础，字段质量直接决定搜索体验（类目、属性、库存、价格、同义词、品牌等） + +--- + +## 3. 身份识别与用户合并（Engagement 的关键能力） + +### 3.1 匿名 → 已知的确定性合并 + +典型触发点： + +- 登录 +- 留资（订阅） +- 下单 + +合并策略（常见）： + +- 以 email/phone/customer_id 作为 canonical user +- 把匿名行为历史挂接到已知用户 + +### 3.2 跨渠道身份桥（Email/SMS/Push/Ads） + +Bloomreach Engagement 这类平台的优势通常在于： + +- 同一用户在不同渠道的触达与互动（open/click/subscribe/unsubscribe）都能回流到同一 profile +- 形成“触达 → 行为 → 转化”的闭环指标 + +--- + +## 4. 外部数据打通（广告/邮件/数据仓库）常见做法 + +### 4.1 广告平台（Meta/Google/TikTok） + +Engagement 类平台通常会： + +- 读取/写入广告受众（分群同步到平台） +- 通过 click id + S2S 转化回传 + 报表拉取做归因与 ROI 分析 + +> 具体“用户匹配提权”方法可复用你们仓库文档：`docs/用户匹配与外部数据打通-平台官方机制提权.md`。 + +### 4.2 数据仓库/数据云（例如 Snowflake） + +公开资料显示 Bloomreach 强调与数据云/仓库的对接，以便： + +- 直接读取企业已沉淀的 customer attributes / events / catalog +- 把分群与触达结果回写（形成数据闭环） + +工程上对应两类模式： + +- **批量同步**：按天/小时把表导入/导出（适合大体量） +- **准实时**：流式/CDC（适合关键事件与实时触达） + +--- + +## 5. 去重、延迟与一致性（Engagement/Discovery 共性） + +- **幂等键**：订单事件用 `order_id`；行为事件用 `event_id` +- **实时层**：站内行为秒级进入用户画像（站内个性化、触发营销） +- **准实时/离线层**：模型训练、用户聚类、商品相似度等批处理 +- **反向修正**：退款/取消会修正 LTV 与归因（必须接入） + +--- + +## 6. 你们自研 SaaS 的可复用点（对照 Bloomreach） + +- 把“Engagement（CDP/营销）”与“Discovery（搜索/商品发现）”的数据需求分层 +- 事件采集 + S2S 事实回传 + Catalog feed 是最稳定三件套 +- 身份合并：匿名 → email/phone/customer_id（确定性优先） +- 触达互动回流（open/click/退订）是“营销型个性化”的关键外部信号 + +--- + +## 7. 参考链接（官方/公开入口） + +- **Bloomreach** + - [Bloomreach 文档中心（入口）](https://documentation.bloomreach.com/) + - [Bloomreach Discovery Web SDK（公开文档）](https://bloomreach.github.io/discovery-web-sdk/index.html) + - [Bloomreach 官网 Docs（入口）](https://www.bloomreach.com/en/docs) +- **关联阅读（本仓库）** + - `docs/全渠道数据整合-广告平台S2S对接手册.md` + - `docs/用户匹配与外部数据打通-平台官方机制提权.md` + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md new file mode 100644 index 0000000..5ef6fd6 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md @@ -0,0 +1,146 @@ +# Dynamic Yield：用户数据获取技术方案（拆解版） + +> 目标：拆解 Dynamic Yield（DY）在“用户数据获取/实时决策/实验优化”的数据层实现，方便你们对标自研个性化引擎 SaaS。 +> +> 说明：DY 的部分文档与实现细节面向客户/合作伙伴账号。本文基于公开资料与行业主流 DY 类产品的落地方式提炼，字段/端点级细节需以你们获取到的 DY 官方文档与 PoC 抓包为准。 + +--- + +## 1. DY 的数据获取 = 事件采集 + 商品/内容 feed + 身份合并 + +### 1.1 事件采集（Web/App） + +**目的**：实时构建 session 意图与短期偏好，驱动 onsite personalization、推荐、A/B 测试。 + +**典型事件**（行业通用）： + +- `page_view` +- `product_view` +- `add_to_cart` +- `checkout_start` +- `purchase` +- `search` + +### 1.2 商品/内容 Feed + +**目的**：推荐与决策需要“可用的候选集合”，feed 的字段质量直接影响推荐与排序。 + +**典型字段**： + +- product_id / sku +- title/description/image +- category/attributes +- price/sale_price +- availability/inventory +- tags/brand + +### 1.3 用户属性与业务事实 + +**目的**：把长期价值与偏好（RFM/LTV/会员等级/历史购买）进入用户画像，支撑更强的策略与实验分层。 + +--- + +## 2. 数据采集方式（DY 类产品典型实现） + +### 2.1 前端 Tag（DY Tag / JS） + +**作用**： + +- 为访客分配匿名 ID（cookie/localStorage 一方） +- 采集页面上下文与行为事件 +- 拉取“决策结果”（推荐/个性化变体/优惠）并渲染 +- 记录实验曝光与转化（A/B、MVT） + +**工程要点**： + +- 异步加载、避免阻塞渲染 +- 事件幂等（event_id） +- 与服务端订单事实对账（purchase 最好 S2S 再补一份） + +### 2.2 服务端 S2S（转化/订单事实） + +**作用**： + +- 提升 purchase/退款/取消的准确性与一致性 +- 支撑 server-side personalization 场景（例如在 edge/SSR 输出个性化） + +**关键字段建议**： + +- order_id（幂等） +- customer identifiers（customer_id / email_sha256 / phone_sha256） +- items、value、currency、timestamp + +### 2.3 平台/工具集成（CDP/Email/Ads） + +DY 常作为“决策层”，因此会对接： + +- CDP（统一事件流） +- Email/SMS（把推荐/人群输出到触达渠道） +- Ads（把人群同步到投放平台、回传转化做归因） + +--- + +## 3. 身份识别与跨设备（DY 类产品常见策略） + +### 3.1 匿名到已知 + +触发点： + +- 登录 +- 留资（订阅） +- 下单 + +做法： + +- 在“识别事件”发生时，把当前匿名 cookie id 与已知标识（email/phone/customer_id）绑定 +- 将历史匿名行为合并到已知画像 + +### 3.2 跨设备 + +- **确定性优先**：email/phone/customer_id +- **匹配增强**：哈希 PII + click id 回传给广告平台，借助平台跨设备图谱提升归因（DY/你们都无法直接拿到平台图谱细节） + +--- + +## 4. 实验与归因：为什么 DY 必须“自己采 + 自己记曝光”？ + +DY 的 A/B 测试与个性化要成立，必须同时拥有： + +- **曝光事件**：用户看到了哪个变体/哪个推荐位（exposure/impression） +- **行为/转化事件**：点击、加购、购买 + +因此在数据获取层，DY 类系统会强制： + +- 在前端记录“谁看到什么”（曝光） +- 在订单侧确认“最终发生什么”（purchase/refund） + +这也是你们自研时必须具备的两条事件链路。 + +--- + +## 5. 去重、延迟与一致性 + +- 曝光/点击等事件：秒级进入决策系统（用于实时策略） +- 订单事实：以 order_id 幂等，分钟级确认并可反向修正（退款/取消） +- 报表与分析：小时级/天级聚合 + +--- + +## 6. 你们自研 SaaS 的可复用点（对照 DY） + +- 把“决策层（实时个性化）”与“事实层（订单/客户/商品）”拆开建管道 +- 曝光事件是 A/B 与个性化归因的基础（必须采集） +- purchase 必须 S2S 幂等回传（order_id） +- 广告平台闭环：click id + S2S 回传 + 报表富化（见 `docs/用户匹配与外部数据打通-平台官方机制提权.md`） + +--- + +## 7. 参考链接（官方/公开入口） + +- **Dynamic Yield** + - [Dynamic Yield Support Center（支持文档入口）](https://support.dynamicyield.com/hc/en-us) +- **关联阅读（本仓库）** + - `docs/全渠道数据整合-广告平台S2S对接手册.md` + - `docs/用户匹配与外部数据打通-平台官方机制提权.md` + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md new file mode 100644 index 0000000..4cc234a --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md @@ -0,0 +1,211 @@ +# Nosto：用户数据获取技术方案（拆解版） + +> 目标：拆解 Nosto 在“用户数据获取/打通/画像更新”层面的常见技术实现，便于你们自研个性化引擎 SaaS 参考。 +> +> 说明：公开互联网上 Nosto 的部分开发者/支持文档存在账号/客户权限门槛；我基于公开信息与行业通行做法进行了结构化提炼。你们在对齐字段/端点级细节时，建议以 Nosto 客户/合作伙伴后台的官方文档为准（并做一次 PoC 抓包验证）。 + +--- + +## 1. Nosto 的“数据获取”总体框架（你可以把它看成 3 条管道） + +### 1.1 行为事件管道（Behavior Events） + +- **来源**：站点前端（Web）/ App（可选）/ 服务端（S2S） +- **目的**：实时更新用户短期意图与会话上下文，用于推荐/个性化/弹窗/分群触发 +- **典型事件**： + - `page_view` / `product_view` / `category_view` + - `search`（站内搜索） + - `add_to_cart` / `remove_from_cart` + - `checkout_start` / `purchase` + +### 1.2 业务事实管道（Commerce Facts） + +- **来源**：电商平台（Shopify/Magento/…）的订单/客户/商品目录同步（API + Webhook） +- **目的**：构建长期画像（RFM、LTV、品类偏好、价格敏感度等）与推荐训练数据 +- **典型对象**： + - 商品目录（SKU、类目、价格、标签、库存） + - 订单事实（line items、折扣、退款/取消） + - 客户事实（邮箱/手机号/会员等级/标签，取决于商家是否有&合规） + +### 1.3 外部渠道管道（Ad/Email/Social Signals） + +- **来源**：广告平台/邮件营销/忠诚度/评价等第三方工具的集成信号（S2S） +- **目的**：把“外部触达/来源”与站内行为闭环，形成更强的归因与分群能力 + +--- + +## 2. 数据采集方式（Nosto 常见实现形态） + +### 2.1 站点前端脚本（Nosto Tag / JS SDK） + +**核心作用**： + +- 生成/读取匿名用户标识（cookie / localStorage 等一方存储） +- 采集页面与商品上下文（例如当前产品 ID、价格、类目等） +- 上报行为事件到 Nosto（低延迟） +- 拉取个性化内容（推荐列表、A/B 试验变体等）并渲染 + +**工程实现要点（行业通用，Nosto 通常也会这么做）**： + +- 异步加载脚本，避免阻塞首屏 +- 事件上报使用 `sendBeacon`/异步 XHR，弱网重试 +- 事件带 `event_id` 做幂等，避免刷新/多次触发重复计数 +- 对“关键事件”（purchase）通常要求服务端再补一份（S2S）以提高准确性 + +### 2.2 服务端 S2S 事件回传（订单/转化） + +**典型用途**： + +- 用服务端确认“最终订单状态”（支付成功、退款、取消） +- 在浏览器追踪受限时补齐转化事件 +- 支持更强的一致性（推荐/分群不会因为前端丢事件而漂移） + +**关键字段（建议你们对齐的通用字段）**： + +- `event_name`: `purchase` / `refund` / `cancel` +- `event_time` +- `order_id`（去重关键） +- `customer_id`（如有）/ `email_sha256`（如合规） +- `items[]`：sku、qty、price、category、brand、tags +- `currency`、`value` + +### 2.3 商品目录与价格库存同步（Feed / Connector） + +Nosto 的个性化推荐对“商品库质量”非常敏感，因此通常会有： + +- **全量导入**（初次接入）：把商品目录、类目、库存、价格、图片、属性标签等导入 +- **增量更新**（日常）：通过平台 webhook 或定时同步更新价格/库存/上下架 + +**商品数据的典型字段**： + +- `product_id / sku` +- `title/description` +- `image_urls` +- `category_path` +- `brand` +- `price / sale_price` +- `availability / inventory` +- `attributes/tags` + +### 2.4 电商平台连接器（Shopify / Magento / BigCommerce…） + +**典型能力**： + +- 读取/订阅：customers、orders、products、inventory +- 绑定：把“匿名行为”与“登录/下单身份”在平台侧的 customer 维度合并 +- 回写（可选）：把分群/推荐结果回写到营销工具（邮件、广告受众等） + +> 在 Shopify 生态里，Nosto 这类工具通常会同时使用：平台 API/Webhooks（业务事实）+ storefront 事件采集（浏览/加购等）。你们可对照 `docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md` 的“主干通道”章节。 + +--- + +## 3. 身份识别与合并（Nosto 的核心：匿名 → 已知 → 跨设备） + +### 3.1 匿名用户识别（Anonymous） + +- **匿名 ID**：由前端脚本生成并持久化（cookie/本地存储） +- **会话 ID**：用于限定“短期意图”（例如最近 30 分钟） + +### 3.2 已知用户识别（Known） + +触发点通常是： + +- 登录 +- 留资（订阅邮箱/短信） +- 下单（checkout） + +在这些节点，Nosto 会把： + +- `anonymous_id` 历史行为 +- 合并到 `customer_id/email/phone` 所对应的长期画像 + +### 3.3 跨设备关联（Cross-device） + +Nosto 类系统的常见策略（也是你们自研建议的路线）： + +- **确定性优先**：email/phone/customer_id 做主键 +- **增强匹配**（合规后）：哈希邮箱/手机号用于广告平台匹配（从而提升归因与跨设备识别） +- **概率信号**（可选）：设备指纹/网络/行为序列，但不作为第一阶段主链路 + +--- + +## 4. 外部数据打通（广告/邮件/忠诚度/评价） + +### 4.1 广告平台（Meta/Google/TikTok） + +Nosto 类产品强调的“聚合搜索与社交平台数据”，工程上通常不是“爬社交”，而是： + +- **入口串联**：从落地页 URL 获取 `fbclid/ttclid/gclid` + UTM +- **站内事件**：用前端脚本/服务端采集购买/加购/浏览 +- **平台闭环**：用平台的官方 S2S 机制回传转化（CAPI/Events API/Conversion Upload） +- **报表富化**：定时拉 campaign/ad/keyword 成本与效果，写入你们的“归因标签” + +详细的“用户匹配与外部数据打通机制”可复用你们仓库已有总结： + +- `docs/用户匹配与外部数据打通-平台官方机制提权.md` + +### 4.2 邮件/短信与 CRM（Klaviyo 等） + +常见链路： + +- Nosto → 邮件系统：把分群/推荐商品列表输出给邮件模板 +- 邮件系统 → Nosto：把 open/click/unsubscribe 等触达互动回流（用于人群质量与策略优化） + +### 4.3 忠诚度/评价（Yotpo 等） + +常见链路： + +- 订单完成触发：发评价邀请、积分发放 +- 评价/等级信号回流：作为“用户偏好/价值”的长期特征 + +--- + +## 5. 去重、延迟与一致性（工程上的“坑”） + +### 5.1 事件去重 + +- 关键事件（purchase/refund）必须可幂等： + - 以 `order_id` 为幂等键（同一订单多次回传只算一次） + - 或使用 `event_id`（保证全局唯一） + +### 5.2 延迟分层 + +- **实时层**：浏览/加购等秒级进入画像（用于推荐） +- **准实时**：订单支付可能分钟级确认（支付网关/平台事件） +- **离线层**：批量重算（商品相似度、用户聚类等） + +### 5.3 事实修正 + +- 退款/取消会“反向修正”用户价值与训练数据 +- 因此必须接入平台侧的退款/取消事件（webhook 或定时对账） + +--- + +## 6. 合规与隐私（GDPR/CCPA + Consent） + +- **同意管理**：在用户未同意前，不应写入营销/广告相关 cookie，也不应回传哈希 PII +- **数据最小化**：只采集必要字段；对 `referrer/landing_url` 做参数白名单与脱敏 +- **分租户隔离**：账号、token、数据源密钥、事件流都必须 tenant 隔离 + +--- + +## 7. 你们自研 SaaS 的可复用点（对照 Nosto） + +- **三管道模型**：行为事件 + 业务事实 + 外部信号（最关键的结构） +- **身份合并主链路**：anonymous_id → customer_id/email/phone（确定性优先） +- **广告平台闭环**：click id + S2S 回传 + 报表富化（不要依赖“平台回传用户行为”） + +--- + +## 8. 参考链接（官方/公开入口） + +- **Nosto** + - [Nosto 官网](https://www.nosto.com/) + - [Nosto Tech Docs（文档入口）](https://docs.nosto.com/) + - [Nosto Support Center（支持文档入口）](https://support.nosto.com/) + - [Nosto Magento2 集成（开源仓库）](https://github.com/Nosto/nosto-magento2) +- **关联阅读（本仓库）** + - `docs/全渠道数据整合-广告平台S2S对接手册.md` + - `docs/用户匹配与外部数据打通-平台官方机制提权.md` + + diff --git a/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md new file mode 100644 index 0000000..81da34a --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md @@ -0,0 +1,700 @@ +# Prefixbox Search API 完整文档 + +*基于公开信息整理的 Prefixbox Search API 技术文档* + +*官方接口文档* +https://api-docs.prefixbox.com/#search-api + + +--- + +## 概述 + +Prefixbox Search API 是一个基于 AI 的电商搜索解决方案，提供全文搜索、向量搜索和混合搜索功能。该 API 支持自动完成、搜索建议、商品过滤、排序等核心电商搜索功能。 + +**核心特性：** +- 混合搜索（文本 + 向量 + GPT 技术） +- 自然语言查询理解 +- 动态重排序 +- 同义词管理 +- 多语言支持 + +--- + +## 1. 基础信息 + +### 1.1 API 端点 + +``` +基础 URL: https://api.prefixbox.com +版本: v1/v2 (根据集成方式不同) +``` + +### 1.2 认证方式 + +**API Key 认证** +- 在 Prefixbox API Portal 的 Profile 页面获取 Search API Key +- 所有请求必须在 Header 中包含：`Authorization: Bearer YOUR_SEARCH_API_KEY` +- 同时需要提供 Search Engine Identifier + +**Header 示例：** +```http +Authorization: Bearer pb_live_abc123xyz... +X-Search-Engine-Id: your-engine-identifier +``` + +--- + +## 2. 核心 API 端点 + +### 2.1 自动完成 API (Autocomplete API) + +**端点：** `GET /autocomplete` + +**功能：** 当用户在搜索框输入时提供实时查询建议、分类建议和商品建议。 + +**请求参数：** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `q` | string | 是 | 用户输入的查询字符串 | +| `limit` | integer | 否 | 返回建议的最大数量 (默认: 10) | +| `type` | string | 否 | 建议类型: `all`, `queries`, `categories`, `products` (默认: all) | +| `lang` | string | 否 | ISO 639-1 语言代码 (如: en, de, fr) | + +**请求示例：** +```http +GET https://api.prefixbox.com/autocomplete?q=apple&limit=8&lang=en +Authorization: Bearer pb_live_abc123xyz... +X-Search-Engine-Id: your-engine-identifier +``` + +**响应格式：** +```json +{ + "query": "apple", + "suggestions": { + "queries": [ + {"text": "apple iphone", "count": 1250}, + {"text": "apple watch", "count": 890}, + {"text": "apple airpods", "count": 650} + ], + "categories": [ + {"id": "cat_001", "name": "Smartphones", "path": "Electronics/Mobile"}, + {"id": "cat_002", "name": "Accessories", "path": "Electronics/Accessories"} + ], + "products": [ + { + "id": "prod_12345", + "name": "Apple iPhone 15 Pro", + "image": "https://cdn.example.com/iphone15.jpg", + "price": 999.99, + "currency": "USD", + "url": "https://store.example.com/products/iphone-15-pro" + } + ] + }, + "latency_ms": 45 +} +``` + +--- + +### 2.2 搜索 API (Search API) + +**端点：** `GET /search` + +**功能：** 执行完整搜索并返回商品结果、过滤器、排序选项等。 + +**请求参数：** + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `q` | string | 是 | 搜索查询字符串 | +| `page` | integer | 否 | 页码 (默认: 1) | +| `page_size` | integer | 否 | 每页商品数量 (默认: 24, 最大: 100) | +| `sort` | string | 否 | 排序方式: `relevance`, `price_asc`, `price_desc`, `newest`, `popularity` | +| `filters` | object | 否 | 过滤器对象 `{"brand": ["Apple", "Samsung"], "price_range": {"min": 500, "max": 1000}}` | +| `lang` | string | 否 | 语言代码 | +| `user_id` | string | 否 | 用户ID（用于个性化）| +| `cdp_data` | object | 否 | 客户数据平台偏好数据 | + +**请求示例：** +```http +GET https://api.prefixbox.com/search?q=running+shoes&page=1&page_size=24&sort=relevance +Authorization: Bearer pb_live_abc123xyz... +X-Search-Engine-Id: your-engine-identifier +``` + +**完整带过滤器的请求：** +```http +GET https://api.prefixbox.com/search?q=running+shoes&filters={"brand":["Nike","Adidas"],"price_range":{"min":50,"max":200},"size":["8","9","10"]} +Authorization: Bearer pb_live_abc123xyz... +X-Search-Engine-Id: your-engine-identifier +``` + +**响应格式：** +```json +{ + "search_id": "search_abc123xyz789", + "query": "running shoes", + "total_results": 1456, + "page": 1, + "page_size": 24, + "total_pages": 61, + "latency_ms": 120, + "products": [ + { + "id": "prod_67890", + "name": "Nike Air Zoom Pegasus", + "description": "Responsive running shoes with Zoom Air cushioning", + "image": "https://cdn.example.com/nike-pegasus.jpg", + "price": 129.99, + "original_price": 159.99, + "currency": "USD", + "url": "https://store.example.com/products/nike-air-zoom-pegasus", + "availability": "in_stock", + "brand": "Nike", + "category": "Running Shoes", + "score": 0.987 + } + ], + "filters": [ + { + "name": "brand", + "type": "multiselect", + "values": [ + {"value": "Nike", "count": 456}, + {"value": "Adidas", "count": 389}, + {"value": "Asics", "count": 234} + ] + }, + { + "name": "price", + "type": "range", + "min": 29.99, + "max": 299.99 + }, + { + "name": "size", + "type": "multiselect", + "values": [ + {"value": "7", "count": 156}, + {"value": "8", "count": 234}, + {"value": "9", "count": 289} + ] + } + ], + "sort_options": [ + {"value": "relevance", "label": "Relevance"}, + {"value": "price_asc", "label": "Price: Low to High"}, + {"value": "price_desc", "label": "Price: High to Low"}, + {"value": "newest", "label": "Newest First"}, + {"value": "popularity", "label": "Most Popular"} + ], + "related_keywords": ["trail running", "marathon shoes", "lightweight trainers"], + "related_categories": [ + {"id": "cat_sports", "name": "Sports & Outdoors"}, + {"id": "cat_footwear", "name": "Footwear"} + ], + "personalized": false, + "ai_reranking": true +} +``` + +--- + +### 2.3 商品详情 API (Product Details API) + +**端点：** `GET /products/{product_id}` + +**功能：** 获取单个商品的详细信息。 + +**请求示例：** +```http +GET https://api.prefixbox.com/products/prod_67890 +Authorization: Bearer pb_live_abc123xyz... +X-Search-Engine-Id: your-engine-identifier +``` + +**响应格式：** +```json +{ + "id": "prod_67890", + "name": "Nike Air Zoom Pegasus", + "description": "Responsive running shoes with Zoom Air cushioning", + "long_description": "Detailed product description...", + "images": [ + "https://cdn.example.com/nike-pegasus-1.jpg", + "https://cdn.example.com/nike-pegasus-2.jpg" + ], + "price": 129.99, + "original_price": 159.99, + "currency": "USD", + "url": "https://store.example.com/products/nike-air-zoom-pegasus", + "availability": "in_stock", + "stock_quantity": 45, + "brand": "Nike", + "category": "Running Shoes", + "attributes": { + "color": ["Black", "White", "Blue"], + "size": ["7", "8", "9", "10", "11", "12"], + "material": "Mesh and Rubber", + "weight": "280g" + }, + "reviews": { + "average_rating": 4.5, + "count": 234 + }, + "tags": ["marathon", "neutral", "cushioned"] +} +``` + +--- + +### 2.4 分类页面 API (Collection API) + +**端点：** `GET /collections/{collection_id}` + +**功能：** 获取分类页面的商品列表。 + +**请求参数：** + +| 参数 | 类型 | 说明 | +|------|------|------| +| `collection_id` | string | 分类ID | +| `page` | integer | 页码 | +| `page_size` | integer | 每页数量 | +| `sort` | string | 排序方式 | +| `filters` | object | 过滤器 | + +**响应格式：** 与 Search API 类似，但返回的是特定分类的商品 + +--- + +## 3. 高级功能 API + +### 3.1 个性化搜索 API + +**端点：** `GET /search/personalized` + +**功能：** 基于用户偏好数据返回个性化排序结果。 + +**请求参数：** +```json +{ + "q": "running shoes", + "user_id": "user_12345", + "cdp_data": { + "preferred_brands": ["Nike", "Adidas"], + "preferred_size": "9", + "preferred_color": "Black", + "past_purchases": ["prod_111", "prod_222"] + } +} +``` + +--- + +### 3.2 AI 重排序 API + +**端点：** `POST /search/rerank` + +**功能：** 基于用户行为数据动态重排搜索结果。 + +**请求参数：** +```json +{ + "search_id": "search_abc123xyz789", + "user_interactions": { + "clicks": ["prod_67890", "prod_67891"], + "hover_time_ms": 2500, + "previous_searches": ["trail running"] + } +} +``` + +--- + +## 4. 推荐 API (AI Recommend) + +### 4.1 相关产品推荐 + +**端点：** `GET /recommendations/related` + +**请求参数：** +```http +GET /recommendations/related?product_id=prod_67890&limit=6 +``` + +**响应格式：** +```json +{ + "product_id": "prod_67890", + "recommendations": [ + { + "id": "prod_67891", + "name": "Nike Dri-FIT Running Socks", + "reason": "Frequently bought together" + }, + { + "id": "prod_67892", + "name": "Nike Running Cap", + "reason": "Similar category" + } + ] +} +``` + +--- + +### 4.2 热门商品推荐 + +**端点：** `GET /recommendations/trending` + +```http +GET /recommendations/trending?category=running&limit=8 +``` + +--- + +## 5. 分析追踪 API + +### 5.1 搜索事件追踪 + +**端点：** `POST /analytics/search-event` + +**功能：** 追踪用户搜索行为以优化搜索相关性。 + +**事件类型：** +- `search_impression` - 搜索结果展示 +- `search_click` - 用户点击结果 +- `search_add_to_cart` - 添加商品到购物车 +- `search_purchase` - 完成购买 + +**请求示例：** +```json +{ + "search_id": "search_abc123xyz789", + "event_type": "search_click", + "user_id": "user_12345", + "product_id": "prod_67890", + "position": 1, + "timestamp": "2025-01-15T10:30:00Z" +} +``` + +--- + +## 6. 实时目录更新 API + +**端点：** `POST /catalog/update` + +**功能：** 实时更新商品目录数据。 + +**请求格式：** +```json +{ + "updates": [ + { + "product_id": "prod_67890", + "field": "stock_quantity", + "value": 23, + "action": "update" + }, + { + "product_id": "prod_67891", + "action": "delete" + } + ] +} +``` + +--- + +## 7. 错误处理 + +### 7.1 HTTP 状态码 + +| 状态码 | 说明 | +|--------|------| +| `200` | 请求成功 | +| `400` | 请求参数错误 | +| `401` | 认证失败 - API Key 无效或缺失 | +| `403` | 权限不足 | +| `404` | 资源未找到 | +| `429` | 请求频率限制 | +| `500` | 服务器内部错误 | + +### 7.2 错误响应格式 + +```json +{ + "error": { + "code": "INVALID_API_KEY", + "message": "The provided API key is invalid or expired.", + "status": 401, + "request_id": "req_123456789" + } +} +``` + +--- + +## 8. 代码集成示例 + +### 8.1 JavaScript/Frontend 集成 + +```javascript +// 初始化 Prefixbox 客户端 +const prefixbox = new PrefixboxClient({ + apiKey: 'pb_live_abc123xyz...', + searchEngineId: 'your-engine-identifier', + language: 'en' +}); + +// 自动完成 +const suggestions = await prefixbox.autocomplete({ + query: 'run', + limit: 8 +}); + +// 搜索 +const searchResults = await prefixbox.search({ + query: 'running shoes', + page: 1, + pageSize: 24, + filters: { + brand: ['Nike', 'Adidas'], + priceRange: { min: 50, max: 200 } + } +}); + +// 追踪事件 +prefixbox.trackEvent('search_click', { + searchId: searchResults.searchId, + productId: 'prod_67890', + position: 1 +}); +``` + +### 8.2 cURL 示例 + +```bash +# 自动完成 +curl -X GET "https://api.prefixbox.com/autocomplete?q=apple&limit=5" \ + -H "Authorization: Bearer pb_live_abc123xyz..." \ + -H "X-Search-Engine-Id: your-engine-identifier" + +# 搜索 +curl -X GET "https://api.prefixbox.com/search?q=laptop&page=1&page_size=24" \ + -H "Authorization: Bearer pb_live_abc123xyz..." \ + -H "X-Search-Engine-Id: your-engine-identifier" +``` + +### 8.3 Python 集成示例 + +```python +import requests + +class PrefixboxClient: + def __init__(self, api_key, search_engine_id): + self.base_url = "https://api.prefixbox.com" + self.headers = { + "Authorization": f"Bearer {api_key}", + "X-Search-Engine-Id": search_engine_id, + "Content-Type": "application/json" + } + + def autocomplete(self, query, limit=10): + endpoint = f"{self.base_url}/autocomplete" + params = {"q": query, "limit": limit} + response = requests.get(endpoint, headers=self.headers, params=params) + return response.json() + + def search(self, query, page=1, page_size=24, filters=None): + endpoint = f"{self.base_url}/search" + params = { + "q": query, + "page": page, + "page_size": page_size + } + if filters: + params["filters"] = filters + + response = requests.get(endpoint, headers=self.headers, params=params) + return response.json() + +# 使用示例 +client = PrefixboxClient( + api_key="pb_live_abc123xyz...", + search_engine_id="your-engine-identifier" +) + +# 执行搜索 +results = client.search( + query="wireless headphones", + filters={"brand": ["Sony", "Bose"], "price_range": {"min": 100, "max": 300}} +) + +print(f"找到 {results['total_results']} 个商品") +for product in results['products']: + print(f"- {product['name']}: ${product['price']}") +``` + +--- + +## 9. SDK 和库 + +Prefixbox 提供以下官方 SDK： + +- **JavaScript SDK**: `npm install @prefixbox/search-js` +- **React SDK**: `npm install @prefixbox/react-search` +- **Python SDK**: `pip install prefixbox-search` +- **PHP SDK**: `composer require prefixbox/search` + +--- + +## 10. 集成方式 + +### 10.1 API 集成 + +**适用场景：** 需要完全自定义 UI 和用户体验 + +**客户职责：** +- 提供商品 Feed URL +- 实现与 Prefixbox API 的通信 +- 实现搜索 UX 界面 +- 实现用户行为追踪 +- Bug 修复和发布 + +**Prefixbox 职责：** +- 在 Admin Portal 配置搜索模块 +- 定制功能需求 +- 测试和报告 Bug +- 运行 A/B 测试 + +### 10.2 前端 JavaScript 集成 + +**适用场景：** 快速部署，最小化开发工作量 + +**客户职责：** +- 提供带 header/footer 的空搜索结果页 +- 提供商品 Feed URL +- 在网站中插入 Prefixbox JavaScript + +**Prefixbox 职责：** +- 配置搜索模块 +- 定制外观和功能 +- 测试、预览和修复 Bug +- 发布到生产环境 + +--- + +## 11. 商品 Feed 格式 + +Prefixbox 要求提供兼容的商品 Feed： + +**必需字段：** +- `id` - 商品唯一标识符 +- `name` - 商品名称 +- `url` - 商品页面 URL +- `price` - 价格 +- `currency` - 货币代码 +- `availability` - 库存状态 + +**推荐字段：** +- `description` - 商品描述 +- `image` - 商品图片 URL +- `brand` - 品牌 +- `category` - 分类 +- `attributes` - 商品属性（颜色、尺寸等） +- `created_at` - 创建日期 +- `popularity_score` - 热门度分数 + +**支持格式：** JSON, XML, CSV + +--- + +## 12. 限制和配额 + +### 12.1 API 请求限制 + +| 套餐 | 月请求配额 | 每分钟限制 | +|------|-----------|-----------| +| Starter | 20,000 | 100 | +| Growth | 200,000 | 500 | +| Grow+ | 600,000-900,000 | 1,000 | +| Enterprise | 自定义 | 自定义 | + +### 12.2 什么算作 API 请求？ + +- **自动完成：** 每个字符输入 = 1 次请求 +- **搜索：** 每次搜索 = 1 次请求 +- **过滤/排序：** 每次操作 = 1 次请求 +- **分页：** 每次翻页 = 1 次请求 + +**示例：** 用户输入 "apple"（6 次自动完成请求）+ 执行搜索（1 次）+ 过滤（1 次）+ 翻页（1 次）= **共 9 次 API 请求** + +--- + +## 13. 支持和资源 + +### 13.1 官方资源 + +- **API 文档门户：** https://api-docs.prefixbox.com +- **开发者中心：** https://developers.prefixbox.com +- **技术文档：** https://www.prefixbox.com/en-us/technical +- **集成指南：** https://www.prefixbox.com/en-us/technical/integration + +### 13.2 支持级别 + +| 支持级别 | 可用套餐 | 响应时间 | +|---------|---------|---------| +| 标准支持 | Starter, Growth | 24-48 小时 | +| 高级支持 | Grow+ | 4 小时 | +| 专属支持 | Enterprise | 1 小时 | + +--- + +## 14. 最佳实践 + +### 14.1 性能优化 + +1. **缓存自动完成结果** - 减少重复请求 +2. **延迟搜索** - 用户停止输入 300ms 后再发送请求 +3. **分页加载** - 使用无限滚动或分页 +4. **图片优化** - 使用 CDN 和适当尺寸的图片 + +### 14.2 提升搜索相关性 + +1. **配置同义词** - 连接不同词汇（如 "sneakers" = "trainers"） +2. **设置字段权重** - 提升重要字段的权重（如 name > description） +3. **使用 A/B 测试** - 测试不同配置对转化率的影响 +4. **分析零结果搜索** - 识别缺失商品或查询问题 + +### 14.3 用户体验 + +1. **显示搜索建议** - 帮助用户快速找到相关查询 +2. **保留搜索上下文** - 支持返回搜索结果 +3. **移动端优化** - 确保触摸友好的界面 +4. **加载状态** - 提供清晰的加载指示 + +--- + +## 15. 常见问题 + +### Q: API 返回 429 错误怎么办？ +A: 表示达到速率限制。实现指数退避重试策略，或升级到更高配额的套餐。 + +### Q: 如何处理多语言搜索？ +A: 在请求中使用 `lang` 参数，并确保商品 Feed 包含翻译内容。 + +### Q: 可以自定义搜索算法吗？ +A: 可以在 Prefixbox Admin Portal 中调整字段权重和同义词规则。 + +### Q: 支持语音搜索吗？ +A: 是的，Prefixbox AI Agent 支持自然语言查询和语音搜索集成。 + +### Q: 如何集成到移动应用？ +A: 通过 API 集成方式，使用 iOS/Android 原生开发或 React Native 调用 REST API。 diff --git a/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md new file mode 100644 index 0000000..3062611 --- /dev/null +++ b/docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md @@ -0,0 +1,204 @@ +# 电商个性化推荐 SaaS 技术方案：数据获取与打通 + +## 1. 引言 + +本技术方案旨在阐述如何构建一个电商个性化推荐 SaaS 平台，重点聚焦于**全渠道数据获取、数据整合与打通**的核心技术实现。我们将借鉴 Nosto 等行业领先者的实践经验，结合当前主流技术栈，设计一套可扩展、高可用且符合数据隐私规范的系统架构。 + +## 2. 核心架构概览 + +个性化推荐 SaaS 平台的核心在于高效地收集、整合和处理来自不同渠道的用户行为数据与业务数据，并在此基础上构建统一的客户视图，为个性化推荐提供坚实的数据基础。以下是整体架构的概览图： + +![架构概览图](https://private-us-east-1.manuscdn.com/sessionFile/MPBkQjAwYEPDQuw5oSNkba/sandbox/owNsnbnP40DtzKCFvilk2L-images_1767771038719_na1fn_L2hvbWUvdWJ1bnR1L2FyY2hpdGVjdHVyZV9kaWFncmFt.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9wcml2YXRlLXVzLWVhc3QtMS5tYW51c2Nkbi5jb20vc2Vzc2lvbkZpbGUvTVBCa1FqQXdZRVBEUXV3NW9TTmtiYS9zYW5kYm94L293TnNuYm5QNDBEdHpLQ0Z2aWxrMkwtaW1hZ2VzXzE3Njc3NzEwMzg3MTlfbmExZm5fTDJodmJXVXZkV0oxYm5SMUwyRnlZMmhwZEdWamRIVnlaVjlrYVdGbmNtRnQucG5nIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzk4NzYxNjAwfX19XX0_&Key-Pair-Id=K2HSFNDJXOU9YS&Signature=FOl36NdZP1NUxEmHSK-TFKC~zEvwPmCzWVcDQVxKtQIzYks0awx2i~PJtck2gywvi9jrDlCpGb49tbzEFEzT6omZ84EDJ4O930Y2mGTFiZcWZDKQY617u9zg3tVh39c6tczcsy47b~YhrTwbks8zANpI9GGdQLqhG0fRM2hkLM1AhJz3bP2qHNjgpsY7cqYDzHgtsNo0qaZVCysAxDFrKLPjXxHfU-udrbJjQ~RZs9mIHsEwP5a3WvHPpxBZMeq4b0Rvi0nmnxITsOwbQrEiovu5X8WdOwtAP-waLewGyFVlAhROuP02hw3BVcwO3Dwq2CVgIbXQru4Q4EDvocarAQ__) + +## 3. 数据采集层：多源异构数据接入 + +数据采集是构建个性化推荐系统的第一步，也是最关键的一步。我们需要建立一套灵活、实时且可靠的数据采集机制，覆盖用户在电商旅程中的所有触点。 + +### 3.1 网站与移动应用行为数据采集 + +* **网站行为数据**：通过 **JavaScript SDK (Pixel)** 部署在电商网站前端，实时捕获用户的页面浏览、点击、加购、收藏、搜索、购买等行为。每个会话通过 `session_id` 或 `cookie_id` 进行标识。SDK 应支持异步加载，避免影响网站性能。 +* **移动应用数据**：通过 **原生 SDK (iOS/Android)** 嵌入到移动应用中，采集与网站类似的用户行为数据。为实现跨设备追踪，移动 SDK 需与网站 SDK 共享用户 ID 机制。 + +**技术实现建议**： +* **消息队列**：采用 **Apache Kafka** 或 **RabbitMQ** 作为数据接入层，处理每秒数十万级别的实时事件流，确保数据不丢失、高吞吐量和低延迟 [1]。 +* **数据格式**：统一采用 JSON 或 Protobuf 格式封装事件数据，包含 `event_type`、`user_id` (如果已知)、`anonymous_id`、`session_id`、`product_id`、`timestamp`、`device_info`、`geo_location` 等关键字段。 + +### 3.2 第三方平台数据接入 + +电商生态系统往往涉及多个外部平台，如社交媒体、广告平台、营销自动化工具等。通过 **Server-to-Server (S2S) API 集成** 是实现这些数据打通的关键，而非简单的客户端 SDK 采集或数据爬取。 + +* **社交媒体平台 (如 Meta/Facebook/Instagram)**： + * **OAuth 2.0 授权**：商家通过 OAuth 2.0 流程授权 SaaS 平台访问其 Meta 商业账户的 API 权限（如 `ads_management`, `ads_read`, `business_management`）。SaaS 平台获取长期访问令牌，用于后续的 API 调用 [2]。 + * **Meta Conversions API (CAPI)**：SaaS 平台作为 Meta 的合作伙伴，通过 CAPI 将服务器端的转化事件（如购买、加购）直接发送给 Meta，弥补浏览器端 Pixel 追踪的不足，提高广告归因的准确性 [3]。这需要服务器到服务器的直接通信，而非通过用户浏览器。 +* **广告平台 (如 Google Ads)**： + * **Google Ads API**：通过 API 获取广告投放数据、点击数据和转化数据。同样，需要商家授权 SaaS 平台访问其 Google Ads 账户 [4]。 + * **Server-Side Tagging**：利用 Google Tag Manager (GTM) 的服务器端容器，将网站事件数据发送到 SaaS 平台的服务器，再由 SaaS 平台转发给 Google Ads，实现更可靠的追踪 [5]。 +* **其他第三方平台 (如 Shopify Flow, LoyaltyLion, Yotpo)**： + * **Webhook 机制**：通过配置 Webhook，当第三方平台发生特定事件（如订单状态变更、会员积分变动、用户评论）时，实时将数据推送到 SaaS 平台的数据接收接口。 + * **API 定时拉取**：对于不支持 Webhook 或需要批量同步的数据，通过定时任务调用第三方平台的 API 进行数据拉取。 + +**关键技术特征**： +* **双向 S2S 架构**：数据直接在商家服务器 → SaaS 平台服务器 → 外部平台服务器之间传输，无需中间人。 +* **实时 + 批量混合**：支持实时事件转发（毫秒级）和定时批量同步（小时级）。 +* **去重机制**：通过 `event_id` 和 `session_id` 避免客户端与服务端事件重复。 + +### 3.3 离线数据导入 + +* **CRM/POS 系统数据**：支持通过 SFTP 文件传输（CSV/JSON 格式）或实时 API 推送的方式，批量导入客户关系管理 (CRM) 系统和销售终端 (POS) 系统中的客户信息、订单历史、会员等级等数据。 +* **CDP 集成**：支持 Segment、mParticle 等标准 CDP 的数据格式，方便商家将已有的 CDP 数据导入。 + +## 4. 身份识别与统一：构建 Identity Graph + +全渠道数据整合的核心挑战之一是**用户身份识别与统一**。不同渠道的用户行为可能由同一个用户产生，但却拥有不同的标识符（如网站 Cookie ID、App 设备 ID、邮箱、手机号）。构建 **Identity Graph (身份图谱)** 是解决这一问题的关键。 + +### 4.1 身份图谱的核心逻辑 + +Identity Graph 旨在将一个用户的不同标识符关联起来，形成一个统一的客户视图 (Customer 360)。 + +| 标识符类型 | 描述 | 示例 | +| :--------------- | :--------------------------------------- | :--------------------------------------- | +| **匿名 ID** | 设备级标识，如 `2c.cId cookie` 值、设备指纹 | `cookie_value_xyz`、`web_1920x1080_chrome_mac` | +| **已知 ID** | 登录用户标识，如 `user_id`、邮箱、手机号 | `user_12345`、`user@example.com`、`+86-138****1234` | +| **关联关系** | 不同 ID 之间的连接关系 | `user_12345` 关联 `cookie_value_xyz` | + +### 4.2 关键技术与匹配策略 + +* **确定性匹配 (Deterministic Matching)**： + * 基于强标识符进行匹配，准确率高。例如，用户登录时，将当前匿名会话的 `anonymous_id` 与其 `user_id` 进行关联。 + * 其他确定性匹配场景包括邮箱订阅、手机号绑定、会员卡号等。 + * **技术实现**：维护一个 ID 映射表，存储 `anonymous_id` 到 `user_id` 的映射关系，并支持实时更新。 +* **概率性匹配 (Probabilistic Matching)**： + * 当缺乏强标识符时，通过算法推测不同匿名行为是否属于同一用户。例如，基于设备指纹 (Device Fingerprint)、行为模式、IP 地址、地理位置等信息进行匹配 [6]。 + * **设备指纹**：结合浏览器类型、操作系统、屏幕分辨率、插件列表、字体等信息生成设备的唯一标识。可集成第三方库如 FingerprintJS。 + * **行为模式**：分析用户在不同设备上的浏览路径、购买偏好、时间规律等，通过机器学习模型计算相似度。 + * **技术实现**： + * **图数据库 (如 Neo4j)**：存储 ID 之间的关联关系，方便进行复杂的关系查询和图算法分析，发现潜在的概率性匹配 [7]。 + * **机器学习模型**：训练分类模型（如逻辑回归、随机森林）来预测不同匿名 ID 属于同一用户的概率。 +* **实时 ID 合并**：当用户登录或提供新的身份信息时，系统应立即合并其历史匿名行为数据，更新用户画像，确保推荐的实时性和准确性。 + +## 5. 数据整合与处理：统一客户数据资产 (CDP) + +将采集到的多源数据和统一身份后的数据进行整合、清洗、转换，最终形成一个统一的客户数据平台 (Customer Data Platform, CDP)，是为个性化推荐提供数据支撑的关键。 + +### 5.1 Lambda 架构与实时流处理 + +为满足“每秒数十万次实时请求”和毫秒级延迟更新用户画像的需求，系统应采用 **Lambda 架构**，结合实时层和批处理层 [8]。 + +* **实时层**： + * **技术栈**：**Apache Flink** 或 **Spark Streaming**。 + * **功能**：处理 Kafka 消息队列中的实时行为流，进行数据清洗、格式转换、实时聚合、特征提取，并毫秒级延迟更新用户画像。 + * **输出**：实时更新的用户画像数据存储到 Redis 等低延迟存储中。 +* **批处理层**： + * **技术栈**：**Apache Spark** 或 **Hadoop MapReduce**。 + * **功能**：每日或定期处理全量历史数据，进行更复杂的离线计算，如用户聚类、商品相似度计算、模型训练、数据修正和补充实时计算结果。 + * **输出**：离线计算结果存储到 HDFS/S3 等分布式存储，并同步到 CDP。 + +### 5.2 CDP 核心数据模型 + +CDP 旨在构建一个全面的客户 360 度视图，包含以下核心数据域： + +| 数据域 | 存储内容 | 典型技术组件 | +| :----------- | :--------------------------------------- | :----------------------- | +| **行为事件** | 点击、浏览、加购、购买等原始事件 | Kafka + Flink | +| **用户属性** | 人口统计、会员等级、RFM 标签、偏好向量 | Redis + PostgreSQL | +| **产品目录** | SKU、价格、库存、类目、标签等商品元数据 | Elasticsearch | +| **场景上下文** | 时间、设备、地理位置、来源渠道 | MongoDB | +| **关系网络** | 用户相似度、商品共现、ID 关联关系 | Neo4j 图数据库 | + +### 5.3 数据存储策略 + +根据数据的访问频率和时效性，采用分层存储策略： + +* **热数据**：用户最近的活跃行为（如最近 50 个行为）存储在 **Redis** 集群中，设置较短的 TTL (Time-To-Live)，支持毫秒级快速读写。 +* **温数据**：近 30 天的行为数据存储在 **Cassandra** 或 **ClickHouse** 等分布式列式数据库中，支持快速查询和聚合分析。 +* **冷数据**：全量历史数据存储在 **S3/HDFS** 等对象存储或分布式文件系统中，用于离线训练和长期归档。 + +## 6. SaaS 平台化设计：多租户与数据安全 + +作为一个 SaaS 平台，多租户架构设计至关重要，需要确保不同商家之间的数据隔离、资源隔离和安全性。 + +### 6.1 多租户隔离策略 + +* **数据隔离**： + * **独立数据库 (Database-per-Tenant)**：为每个商家分配独立的数据库实例，提供最强的数据隔离性，但成本较高，管理复杂 [9]。 + * **独立 Schema (Schema-per-Tenant)**：在共享数据库中为每个商家创建独立的 Schema，数据隔离性良好，成本适中 [9]。 + * **共享数据库，通过 Tenant ID 隔离 (Shared Database with Tenant ID)**：所有商家数据存储在同一个数据库中，通过在每张表中添加 `tenant_id` 字段进行逻辑隔离。实现简单，成本最低，但需要严格的应用程序逻辑控制数据访问 [9]。 + * **建议**：对于核心敏感数据（如用户画像、行为事件），可采用独立 Schema 或独立数据库；对于公共数据（如商品目录模板），可采用共享数据库加 `tenant_id` 隔离。在 Kafka 消息队列中，可为每个租户创建独立 Topic 或使用 `tenant_id` 作为消息 Key 进行分区。 +* **资源隔离**： + * **Kubernetes 命名空间 (Namespace)**：在 Kubernetes 集群中为每个商家创建独立的命名空间，通过资源配额 (Resource Quotas) 限制 CPU、内存等资源使用，防止“邻居干扰”问题 [10]。 + * **容器化部署**：将各个服务（数据采集、流处理、API 服务等）容器化，通过 Docker 和 Kubernetes 进行部署和管理。 +* **API 隔离**：为每个商家提供独立的 `accountID` 和 API Key，确保 API 调用的安全性和隔离性。 + +### 6.2 数据安全与合规 + +* **数据加密**：所有敏感数据（如用户 PII、支付信息）在传输和存储过程中必须进行加密。使用 TLS/SSL 保护数据传输，使用 AES-256 等算法加密静态数据。 +* **访问控制**：实施严格的基于角色的访问控制 (RBAC)，确保只有授权用户才能访问特定数据和功能。 +* **隐私合规**： + * **GDPR (通用数据保护条例)** 和 **CCPA (加州消费者隐私法案)**：确保数据采集、存储、处理和共享符合 GDPR 和 CCPA 等隐私法规的要求 [11]。 + * **用户数据删除**：提供用户数据删除功能，支持用户行使“被遗忘权”。 + * **数据最小化**：只收集和存储必要的、与业务目的相关的数据。 + * **透明度**：向用户清晰说明数据收集和使用政策。 + +## 7. 实施路线图 (数据获取与打通阶段) + +### 7.1 第一阶段：MVP (数据采集与身份识别) + +* **基础设施搭建**： + * 消息队列：Kafka (3 节点集群) + * 流处理：Flink on Kubernetes + * 缓存：Redis Cluster (6 节点) + * 数据库：PostgreSQL (用户数据) + Elasticsearch (商品目录) + * API 网关：Kong/AWS API Gateway +* **核心功能实现**： + * **JavaScript SDK**：页面埋点、Cookie 管理、行为上报。 + * **身份服务**：匿名 ID 生成、登录态关联、ID 映射表。 + * **数据接收 API**：接收网站/APP SDK 上报的事件数据，写入 Kafka。 + * **管理后台**：商家注册、API Key 管理、数据源配置。 +* **数据模型设计**： + * `user_events` 表：存储原始用户行为事件。 + * `user_identity_map` 表：存储匿名 ID 与已知 ID 的映射关系。 + +### 7.2 第二阶段：全渠道整合与 CDP 建设 + +* **扩展数据源**： + * **移动端 SDK**：iOS/Android 埋点采集。 + * **CRM 对接**：Salesforce、HubSpot API 集成。 + * **营销平台对接**：Klavyio、Mailchimp 获取邮件互动数据。 + * **广告平台 S2S 集成**：Meta CAPI、Google Ads API/Server-Side Tagging。 +* **增强身份识别**： + * **设备指纹库**：集成 FingerprintJS/Thumbor。 + * **图谱算法**：使用 Neo4j 存储 ID 关联关系，实现概率匹配。 + * **实时 ID 合并引擎**：确保用户身份实时统一。 +* **CDP 建设**： + * **实时用户画像**：Flink 处理实时流，更新 Redis 中的用户画像。 + * **统一客户数据模型**：设计并实现 CDP 核心数据模型，整合行为、属性、产品、场景数据。 + * **数据存储分层**：Redis (热数据)、Cassandra (温数据)、S3/HDFS (冷数据)。 + +## 8. 关键技术挑战与应对方案 + +| 挑战 | 应对方案 | +| :------------- | :------------------------------------------- | +| **数据延迟** | Flink 实时流处理，Redis 缓存热数据，P99 延迟 < 200ms | +| **ID 关联准确率** | 确定性 + 概率性匹配，持续学习优化，初期 95% 准确率，通过反馈数据迭代 | +| **商品库同步** | 支持增量同步 + 全量校对，延迟 < 1 分钟 | +| **多租户数据隔离** | 独立 Schema/数据库 + Tenant ID 逻辑隔离，Kubernetes 资源配额 | +| **数据安全合规** | 数据加密、RBAC、GDPR/CCPA 合规，支持用户数据删除 | +| **系统稳定性** | 熔断、限流、降级三件套，多云部署，99.9% 可用性 | + +## 9. 总结 + +本方案详细阐述了构建电商个性化推荐 SaaS 平台在**数据获取与打通**方面的技术实现路径。通过建立强大的数据采集层、智能的身份识别服务、高效的数据整合处理机制以及安全的多租户架构，我们将能够为商家提供一个稳定、可靠且功能强大的个性化推荐基础平台，助力其实现业务增长。 + +## 10. 参考文献 + +[1] Apache Kafka. [https://kafka.apache.org/](https://kafka.apache.org/) +[2] Meta for Developers - OAuth 2.0. [https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) +[3] Meta for Developers - Conversions API. [https://developers.facebook.com/docs/marketing-api/conversions-api/](https://developers.facebook.com/docs/marketing-api/conversions-api/) +[4] Google Ads API. [https://developers.google.com/google-ads/api/docs/start](https://developers.google.com/google-ads/api/docs/start) +[5] Google Tag Manager - Server-side tagging. [https://developers.google.com/tag-platform/tag-manager/server-side/intro](https://developers.google.com/tag-platform/tag-manager/server-side/intro) +[6] Identity Resolution: Unifying User Profiles. [https://www.okta.com/identity-101/identity-resolution/](https://www.okta.com/identity-101/identity-resolution/) +[7] Neo4j Graph Database. [https://neo4j.com/](https://neo4j.com/) +[8] Lambda Architecture. [https://en.wikipedia.org/wiki/Lambda_architecture](https://en.wikipedia.org/wiki/Lambda_architecture) +[9] Data Isolation and Sharding Architectures for Multi-Tenant Systems. [https://medium.com/@justhamade/data-isolation-and-sharding-architectures-for-multi-tenant-systems-20584ae2bc31](https://medium.com/@justhamade/data-isolation-and-sharding-architectures-for-multi-tenant-systems-20584ae2bc31) +[10] Kubernetes Namespaces. [https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +[11] GDPR for SaaS: 8 Steps to Ensure Compliance. [https://www.cookieyes.com/blog/gdpr-for-saas/](https://www.cookieyes.com/blog/gdpr-for-saas/) diff --git a/docs/proto/user_action.proto b/docs/proto/user_action.proto new file mode 100644 index 0000000..75a4b9d --- /dev/null +++ b/docs/proto/user_action.proto @@ -0,0 +1,296 @@ +syntax = "proto3"; + +package ua.v1; + +// UA: 站内全站埋点统一事件模型（推荐/搜索/画像/转化） +// +// 设计要点： +// - 单条事件统一骨架（identity/time/page/trace/device + oneof event） +// - trace_id 串联一次搜索/推荐请求产生的曝光与后续点击/详情/加购等 +// - 支持 pageview 携带曝光列表、搜索筛选上下文、购物车/结账快照、购买明细 + +// 详细事件子类型（可选），用于更细粒度区分同一主类型下的来源/动作。 +// 例如：CLICK + SEARCH_RESULT_ITEM_CLICK / RECOMMEND_ITEM_CLICK +enum EventId { + EVENT_ID_UNSPECIFIED = 0; + + // 搜索相关 (1-99) + EVENT_ID_SEARCH_SUBMIT = 1; + EVENT_ID_SEARCH_SUGGESTION_CLICK = 2; + EVENT_ID_SEARCH_RESULT_EXPOSURE = 3; + EVENT_ID_SEARCH_RESULT_ITEM_CLICK = 4; + + // 推荐相关 (100-199) + EVENT_ID_RECOMMEND_REQUEST = 100; + EVENT_ID_RECOMMEND_EXPOSURE = 101; + EVENT_ID_RECOMMEND_ITEM_CLICK = 102; + + // 页面/浏览 (200-299) + EVENT_ID_PAGE_VIEW = 200; + EVENT_ID_VIEW_ITEM = 201; + + // 购物车/结账 (300-399) + EVENT_ID_ADD_TO_CART = 300; + EVENT_ID_REMOVE_FROM_CART = 301; + EVENT_ID_CART_VIEW = 302; + EVENT_ID_CHECKOUT_STEP_VIEW = 330; + EVENT_ID_CHECKOUT_STEP_COMPLETE = 331; + + // 购买 (400-499) + EVENT_ID_PURCHASE = 400; + EVENT_ID_PAYMENT_SUCCESS = 401; +} + +// 行为主类型（用于统计/分流；细分用 EventId 或各事件内字段表达） +enum ActionType { + ACTION_TYPE_UNSPECIFIED = 0; + ACTION_TYPE_PAGEVIEW = 1; + ACTION_TYPE_EXPOSURE = 2; + ACTION_TYPE_CLICK = 3; + ACTION_TYPE_VIEW_ITEM = 4; + ACTION_TYPE_ADD_TO_CART = 5; + ACTION_TYPE_REMOVE_FROM_CART = 6; + ACTION_TYPE_CART = 7; + ACTION_TYPE_CHECKOUT = 8; + ACTION_TYPE_PURCHASE = 9; + ACTION_TYPE_SEARCH = 10; + ACTION_TYPE_FILTER = 11; +} + +// 页面类型（可按业务扩展；无法归类时用 OTHER 并填 page_id/page_name/url） +enum PageType { + PAGE_TYPE_UNSPECIFIED = 0; + PAGE_TYPE_HOME = 1; + PAGE_TYPE_SEARCH_RESULT = 2; + PAGE_TYPE_CATEGORY_PAGE = 3; + PAGE_TYPE_COLLECTION_PAGE = 4; // 活动页/专题页/聚合页 + PAGE_TYPE_PRODUCT_DETAIL = 5; + PAGE_TYPE_CART_PAGE = 6; + PAGE_TYPE_CHECKOUT_PAGE = 7; + PAGE_TYPE_ORDER_CONFIRM = 8; + PAGE_TYPE_MERCHANT_SHOP = 9; + PAGE_TYPE_OTHER = 99; +} + +// 排序方式（无法覆盖时，用 CUSTOM 并填 sort_key） +enum SortType { + SORT_TYPE_UNSPECIFIED = 0; + SORT_TYPE_RELEVANCE = 1; + SORT_TYPE_PRICE_ASC = 2; + SORT_TYPE_PRICE_DESC = 3; + SORT_TYPE_SALES_DESC = 4; + SORT_TYPE_NEWEST_DESC = 5; + SORT_TYPE_CUSTOM = 99; +} + +// 结账阶段（可按业务扩展） +enum CheckoutStep { + CHECKOUT_STEP_UNSPECIFIED = 0; + CHECKOUT_STEP_CART = 1; + CHECKOUT_STEP_SHIPPING = 2; + CHECKOUT_STEP_PAYMENT = 3; + CHECKOUT_STEP_REVIEW = 4; + CHECKOUT_STEP_COMPLETE = 5; +} + +message UserActionEvent { + // 基础标识 + string tenant_id = 1; // 租户/店铺/商家ID + string user_id = 2; // 登录用户ID（未登录可为空） + string anonymous_id = 3; // 匿名用户ID（建议 cookie 级别稳定） + string device_id = 4; // 设备指纹（可选） + string ip = 5; // 客户端IP（可选） + + // 时间 + int64 event_timestamp_ms = 6; // 行为发生时刻（毫秒） + + // 事件类型 + ActionType action_type = 7; // 行为主类型 + EventId event_id = 8; // 详细事件子类型（可选） + + // 公共上下文 + PageInfo page = 9; + TraceInfo trace = 10; + DeviceProfile device = 11; + ContextProfile context = 12; + + // 具体事件载荷 + oneof event { + PageViewEvent page_view = 20; + ExposureEvent exposure = 21; + ClickEvent click = 22; + ViewItemEvent view_item = 23; + SearchEvent search = 24; + FilterEvent filter = 25; + CartEvent cart = 26; + CheckoutEvent checkout = 27; + PurchaseEvent purchase = 28; + } + + Extra extra = 90; // 扩展字段（灵活KV） +} + +message PageInfo { + PageType page_type = 1; + string page_id = 2; // 页面唯一标识（如活动页ID/类目ID/自定义key） + string page_name = 3; // 可读名称（可选） + string url = 4; // 完整URL（可选） + string path = 5; // path（可选） + string refer_url = 6; // 来源URL（可选） + string lang = 7; // 页面语言（可选） + + // 模块信息：用于表达曝光/点击发生在哪个模块 + string module_id = 20; // e.g. "search_result", "recommend_home" + int32 position = 21; // 在本屏/本列表的位置（从0开始；无则填 -1） +} + +message TraceInfo { + // 串联一次搜索/推荐请求产生的曝光与后续点击/详情/加购 + string trace_id = 1; + + // 会话ID（同一次访问，跨多个 trace_id） + string session_id = 2; + + // 实验/流量 + string abtest_id = 10; // 实验ID、流量组标识 +} + +message ContextProfile { + // 业务自定义来源（如 "shopify-web", "app", "mini-program"） + string source = 1; +} + +message DeviceProfile { + string os = 1; // e.g. "Windows", "macOS", "iOS", "Android" + string user_agent = 2; // 浏览器UA + string cookie_id = 3; // 首次访问生成的持久化Cookie ID + int32 viewport_width = 4; + int32 viewport_height = 5; +} + +// 商品/内容基础信息（埋点侧尽量带齐，便于离线特征构建） +message Item { + string spu_id = 1; + string sku_id = 2; + string snapshot_id = 3; // 特征快照ID（可选） + string category_id = 4; + string brand_id = 5; + string title = 6; + + // 可选：价格与属性（若能拿到） + string currency = 20; // e.g. "USD" + double price = 21; // 单价 + map properties = 30; // 颜色/尺码等扩展属性 +} + +// 搜索上下文：既可作为 SearchEvent 的主体，也可挂载在 exposure/click 上 +message SearchContext { + string search_query = 1; + string suggestion_used = 2; + int32 result_count = 3; + int32 page_number = 4; // 从1开始 + SortType sort_type = 5; + string sort_key = 6; // sort_type=CUSTOM 时使用 + repeated FilterParam filters = 7; +} + +message FilterParam { + string key = 1; // e.g. "color", "price" + repeated string values = 2; // e.g. ["red","blue"] + string op = 3; // e.g. "in", "range" +} + +// Pageview：建议可携带“本次渲染曝光的商品列表”（用于特征与归因） +message PageViewEvent { + int64 dwell_time_ms = 1; // 停留时长（如无法计算可缺省） + repeated ExposedItem exposed_items = 2; // 可选：首屏/本次渲染曝光 + SearchContext search_context = 3; // 若该 pageview 属于搜索结果页，可填 +} + +// 曝光：可用于列表页/推荐位/活动页等 +message ExposureEvent { + repeated ExposedItem items = 1; // 一次曝光可批量上报多商品 + SearchContext search_context = 2; // 搜索流量曝光需填（推荐流量可不填） +} + +message ExposedItem { + Item item = 1; + int32 position = 2; // 从0开始 + string module_id = 3; // e.g. "search_result" +} + +// 点击：用于列表/推荐位点击商品等 +message ClickEvent { + Item item = 1; + int32 position = 2; + string module_id = 3; + SearchContext search_context = 4; // 若点击发生在搜索结果中，需填 +} + +// 详情页浏览：建议与 Pageview 区分，便于训练“商品级浏览”序列 +message ViewItemEvent { + Item item = 1; + int64 dwell_time_ms = 2; // 在详情页停留（建议） +} + +// 搜索：提交/改词/使用建议词等 +message SearchEvent { + SearchContext search_context = 1; +} + +// 筛选：筛选条件变更（也可与搜索事件合并；这里单独提供便于实时系统消费） +message FilterEvent { + SearchContext search_context = 1; +} + +// 购物车：加购/移除/查看等，建议尽量携带快照 +message CartEvent { + // 动作相关商品（对 add/remove 有意义） + Item item = 1; + int32 quantity = 2; // 加/减数量（可选） + + CartSnapshot cart_snapshot = 10; // 当前购物车快照（强烈建议） +} + +message CartSnapshot { + repeated CartItem items = 1; + string currency = 2; + double cart_total_value = 3; // 购物车总价（可选） +} + +message CartItem { + Item item = 1; + int32 quantity = 2; + double line_total_value = 3; // 行总价（可选） +} + +// 结账：shipping/payment 等阶段状态 +message CheckoutEvent { + CheckoutStep step = 1; + string shipping_country = 2; // 用于跨境/税费/配送推荐 + string payment_method = 3; // 可选 + CartSnapshot cart_snapshot = 10; +} + +// 购买：订单完成/支付成功等 +message PurchaseEvent { + string order_id = 1; + string currency = 2; + double order_total_value = 3; + repeated PurchasedItem items = 4; + + // 若能保留主要来源 trace，用于归因（可选） + string attribution_trace_id = 10; +} + +message PurchasedItem { + Item item = 1; + int32 quantity = 2; + double paid_price = 3; // 实付单价（可选） +} + +message Extra { + map debug_info = 1; +} + + diff --git a/docs/全渠道数据整合-广告平台S2S对接手册.md b/docs/全渠道数据整合-广告平台S2S对接手册.md deleted file mode 100644 index c534bc2..0000000 --- a/docs/全渠道数据整合-广告平台S2S对接手册.md +++ /dev/null @@ -1,409 +0,0 @@ -# 全渠道数据整合：广告/社交平台 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` 做脱敏与参数白名单 - - diff --git a/docs/用户匹配与外部数据打通-平台官方机制提权.md b/docs/用户匹配与外部数据打通-平台官方机制提权.md deleted file mode 100644 index 8ea6a33..0000000 --- a/docs/用户匹配与外部数据打通-平台官方机制提权.md +++ /dev/null @@ -1,281 +0,0 @@ -# 用户匹配与外部数据打通：平台官方机制提权（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` - - diff --git a/docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md b/docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md deleted file mode 100644 index dab52a9..0000000 --- a/docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md +++ /dev/null @@ -1,135 +0,0 @@ -# Bloomreach：用户数据获取技术方案（拆解版：Engagement / Discovery） - -> 目标：拆解 Bloomreach 在“用户数据获取/统一/激活”的技术路径，覆盖 Bloomreach Engagement（原 Exponea，偏 CDP+营销自动化）与 Bloomreach Discovery（偏搜索/商品发现）。 -> -> 说明：Bloomreach 的开发者文档体系较大，且部分内容面向客户/合作伙伴账号。本文以公开资料与行业通用实现方式做结构化提炼；字段/端点级细节请以你们实际拿到的 Bloomreach 官方文档与 PoC 验证为准。 - ---- - -## 1. Bloomreach 的“取数目标”分两条产品线 - -### 1.1 Engagement（CDP / Marketing Automation） - -**核心目标**：把多渠道事件与用户属性汇总为 Customer 360，并在邮件/短信/推送/站内等渠道做实时触达与分群。 - -### 1.2 Discovery（Search / Merchandising） - -**核心目标**：让搜索/类目页/推荐能基于： - -- 高质量商品目录 -- 用户行为与查询意图（站内搜索词、点击、加购、购买） - -做排序与推荐优化。 - ---- - -## 2. 数据获取的 4 条主通道（Bloomreach 常见架构） - -### 2.1 Web 事件采集（JS SDK / Tag） - -**用途**：采集站内行为（浏览、点击、搜索、加购、结账开始等），并生成匿名 ID / 会话 ID。 - -**你能获得的数据类型**： - -- 页面/商品/类目上下文（URL、product_id、category、price 等） -- 行为事件序列（view → add_to_cart → purchase） -- 会话/设备信号（device、browser、language、geo 近似等） - -### 2.2 Mobile 事件采集（iOS/Android SDK，可选） - -**用途**：App 内事件与身份（device id / login id）进入同一用户画像，用于跨设备与多渠道触达。 - -### 2.3 服务端 S2S 事件与属性导入（Events API / Attributes Import） - -**用途**： - -- 订单支付、退款、取消等“最终事实”由服务端回传，保证一致性 -- CRM/会员/线下交易等属性导入，丰富 Customer 360 - -**典型字段（你们实现时建议对齐）**： - -- `customer_id` / `email_sha256` / `phone_sha256` -- `event_name`（purchase/refund/loyalty_level_changed…） -- `event_time` -- `order_id`（幂等） -- `items[]`（sku/qty/price/category） -- `consent`（是否允许营销/广告/分析） - -### 2.4 商品目录/内容目录导入（Feed / Connector） - -**Engagement 视角**： - -- 把 catalog 作为“推荐与模板渲染”的素材库（邮件/站内推荐等） - -**Discovery 视角**： - -- catalog 是搜索与排序的基础，字段质量直接决定搜索体验（类目、属性、库存、价格、同义词、品牌等） - ---- - -## 3. 身份识别与用户合并（Engagement 的关键能力） - -### 3.1 匿名 → 已知的确定性合并 - -典型触发点： - -- 登录 -- 留资（订阅） -- 下单 - -合并策略（常见）： - -- 以 email/phone/customer_id 作为 canonical user -- 把匿名行为历史挂接到已知用户 - -### 3.2 跨渠道身份桥（Email/SMS/Push/Ads） - -Bloomreach Engagement 这类平台的优势通常在于： - -- 同一用户在不同渠道的触达与互动（open/click/subscribe/unsubscribe）都能回流到同一 profile -- 形成“触达 → 行为 → 转化”的闭环指标 - ---- - -## 4. 外部数据打通（广告/邮件/数据仓库）常见做法 - -### 4.1 广告平台（Meta/Google/TikTok） - -Engagement 类平台通常会： - -- 读取/写入广告受众（分群同步到平台） -- 通过 click id + S2S 转化回传 + 报表拉取做归因与 ROI 分析 - -> 具体“用户匹配提权”方法可复用你们仓库文档：`docs/用户匹配与外部数据打通-平台官方机制提权.md`。 - -### 4.2 数据仓库/数据云（例如 Snowflake） - -公开资料显示 Bloomreach 强调与数据云/仓库的对接，以便： - -- 直接读取企业已沉淀的 customer attributes / events / catalog -- 把分群与触达结果回写（形成数据闭环） - -工程上对应两类模式： - -- **批量同步**：按天/小时把表导入/导出（适合大体量） -- **准实时**：流式/CDC（适合关键事件与实时触达） - ---- - -## 5. 去重、延迟与一致性（Engagement/Discovery 共性） - -- **幂等键**：订单事件用 `order_id`；行为事件用 `event_id` -- **实时层**：站内行为秒级进入用户画像（站内个性化、触发营销） -- **准实时/离线层**：模型训练、用户聚类、商品相似度等批处理 -- **反向修正**：退款/取消会修正 LTV 与归因（必须接入） - ---- - -## 6. 你们自研 SaaS 的可复用点（对照 Bloomreach） - -- 把“Engagement（CDP/营销）”与“Discovery（搜索/商品发现）”的数据需求分层 -- 事件采集 + S2S 事实回传 + Catalog feed 是最稳定三件套 -- 身份合并：匿名 → email/phone/customer_id（确定性优先） -- 触达互动回流（open/click/退订）是“营销型个性化”的关键外部信号 - - diff --git a/docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md b/docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md deleted file mode 100644 index c30f993..0000000 --- a/docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md +++ /dev/null @@ -1,136 +0,0 @@ -# Dynamic Yield：用户数据获取技术方案（拆解版） - -> 目标：拆解 Dynamic Yield（DY）在“用户数据获取/实时决策/实验优化”的数据层实现，方便你们对标自研个性化引擎 SaaS。 -> -> 说明：DY 的部分文档与实现细节面向客户/合作伙伴账号。本文基于公开资料与行业主流 DY 类产品的落地方式提炼，字段/端点级细节需以你们获取到的 DY 官方文档与 PoC 抓包为准。 - ---- - -## 1. DY 的数据获取 = 事件采集 + 商品/内容 feed + 身份合并 - -### 1.1 事件采集（Web/App） - -**目的**：实时构建 session 意图与短期偏好，驱动 onsite personalization、推荐、A/B 测试。 - -**典型事件**（行业通用）： - -- `page_view` -- `product_view` -- `add_to_cart` -- `checkout_start` -- `purchase` -- `search` - -### 1.2 商品/内容 Feed - -**目的**：推荐与决策需要“可用的候选集合”，feed 的字段质量直接影响推荐与排序。 - -**典型字段**： - -- product_id / sku -- title/description/image -- category/attributes -- price/sale_price -- availability/inventory -- tags/brand - -### 1.3 用户属性与业务事实 - -**目的**：把长期价值与偏好（RFM/LTV/会员等级/历史购买）进入用户画像，支撑更强的策略与实验分层。 - ---- - -## 2. 数据采集方式（DY 类产品典型实现） - -### 2.1 前端 Tag（DY Tag / JS） - -**作用**： - -- 为访客分配匿名 ID（cookie/localStorage 一方） -- 采集页面上下文与行为事件 -- 拉取“决策结果”（推荐/个性化变体/优惠）并渲染 -- 记录实验曝光与转化（A/B、MVT） - -**工程要点**： - -- 异步加载、避免阻塞渲染 -- 事件幂等（event_id） -- 与服务端订单事实对账（purchase 最好 S2S 再补一份） - -### 2.2 服务端 S2S（转化/订单事实） - -**作用**： - -- 提升 purchase/退款/取消的准确性与一致性 -- 支撑 server-side personalization 场景（例如在 edge/SSR 输出个性化） - -**关键字段建议**： - -- order_id（幂等） -- customer identifiers（customer_id / email_sha256 / phone_sha256） -- items、value、currency、timestamp - -### 2.3 平台/工具集成（CDP/Email/Ads） - -DY 常作为“决策层”，因此会对接： - -- CDP（统一事件流） -- Email/SMS（把推荐/人群输出到触达渠道） -- Ads（把人群同步到投放平台、回传转化做归因） - ---- - -## 3. 身份识别与跨设备（DY 类产品常见策略） - -### 3.1 匿名到已知 - -触发点： - -- 登录 -- 留资（订阅） -- 下单 - -做法： - -- 在“识别事件”发生时，把当前匿名 cookie id 与已知标识（email/phone/customer_id）绑定 -- 将历史匿名行为合并到已知画像 - -### 3.2 跨设备 - -- **确定性优先**：email/phone/customer_id -- **匹配增强**：哈希 PII + click id 回传给广告平台，借助平台跨设备图谱提升归因（DY/你们都无法直接拿到平台图谱细节） - ---- - -## 4. 实验与归因：为什么 DY 必须“自己采 + 自己记曝光”？ - -DY 的 A/B 测试与个性化要成立，必须同时拥有： - -- **曝光事件**：用户看到了哪个变体/哪个推荐位（exposure/impression） -- **行为/转化事件**：点击、加购、购买 - -因此在数据获取层，DY 类系统会强制： - -- 在前端记录“谁看到什么”（曝光） -- 在订单侧确认“最终发生什么”（purchase/refund） - -这也是你们自研时必须具备的两条事件链路。 - ---- - -## 5. 去重、延迟与一致性 - -- 曝光/点击等事件：秒级进入决策系统（用于实时策略） -- 订单事实：以 order_id 幂等，分钟级确认并可反向修正（退款/取消） -- 报表与分析：小时级/天级聚合 - ---- - -## 6. 你们自研 SaaS 的可复用点（对照 DY） - -- 把“决策层（实时个性化）”与“事实层（订单/客户/商品）”拆开建管道 -- 曝光事件是 A/B 与个性化归因的基础（必须采集） -- purchase 必须 S2S 幂等回传（order_id） -- 广告平台闭环：click id + S2S 回传 + 报表富化（见 `docs/用户匹配与外部数据打通-平台官方机制提权.md`） - - diff --git a/docs/竞品参考文档/Nosto-用户数据获取技术方案.md b/docs/竞品参考文档/Nosto-用户数据获取技术方案.md deleted file mode 100644 index 05dde9d..0000000 --- a/docs/竞品参考文档/Nosto-用户数据获取技术方案.md +++ /dev/null @@ -1,198 +0,0 @@ -# Nosto：用户数据获取技术方案（拆解版） - -> 目标：拆解 Nosto 在“用户数据获取/打通/画像更新”层面的常见技术实现，便于你们自研个性化引擎 SaaS 参考。 -> -> 说明：公开互联网上 Nosto 的部分开发者/支持文档存在账号/客户权限门槛；我基于公开信息与行业通行做法进行了结构化提炼。你们在对齐字段/端点级细节时，建议以 Nosto 客户/合作伙伴后台的官方文档为准（并做一次 PoC 抓包验证）。 - ---- - -## 1. Nosto 的“数据获取”总体框架（你可以把它看成 3 条管道） - -### 1.1 行为事件管道（Behavior Events） - -- **来源**：站点前端（Web）/ App（可选）/ 服务端（S2S） -- **目的**：实时更新用户短期意图与会话上下文，用于推荐/个性化/弹窗/分群触发 -- **典型事件**： - - `page_view` / `product_view` / `category_view` - - `search`（站内搜索） - - `add_to_cart` / `remove_from_cart` - - `checkout_start` / `purchase` - -### 1.2 业务事实管道（Commerce Facts） - -- **来源**：电商平台（Shopify/Magento/…）的订单/客户/商品目录同步（API + Webhook） -- **目的**：构建长期画像（RFM、LTV、品类偏好、价格敏感度等）与推荐训练数据 -- **典型对象**： - - 商品目录（SKU、类目、价格、标签、库存） - - 订单事实（line items、折扣、退款/取消） - - 客户事实（邮箱/手机号/会员等级/标签，取决于商家是否有&合规） - -### 1.3 外部渠道管道（Ad/Email/Social Signals） - -- **来源**：广告平台/邮件营销/忠诚度/评价等第三方工具的集成信号（S2S） -- **目的**：把“外部触达/来源”与站内行为闭环，形成更强的归因与分群能力 - ---- - -## 2. 数据采集方式（Nosto 常见实现形态） - -### 2.1 站点前端脚本（Nosto Tag / JS SDK） - -**核心作用**： - -- 生成/读取匿名用户标识（cookie / localStorage 等一方存储） -- 采集页面与商品上下文（例如当前产品 ID、价格、类目等） -- 上报行为事件到 Nosto（低延迟） -- 拉取个性化内容（推荐列表、A/B 试验变体等）并渲染 - -**工程实现要点（行业通用，Nosto 通常也会这么做）**： - -- 异步加载脚本，避免阻塞首屏 -- 事件上报使用 `sendBeacon`/异步 XHR，弱网重试 -- 事件带 `event_id` 做幂等，避免刷新/多次触发重复计数 -- 对“关键事件”（purchase）通常要求服务端再补一份（S2S）以提高准确性 - -### 2.2 服务端 S2S 事件回传（订单/转化） - -**典型用途**： - -- 用服务端确认“最终订单状态”（支付成功、退款、取消） -- 在浏览器追踪受限时补齐转化事件 -- 支持更强的一致性（推荐/分群不会因为前端丢事件而漂移） - -**关键字段（建议你们对齐的通用字段）**： - -- `event_name`: `purchase` / `refund` / `cancel` -- `event_time` -- `order_id`（去重关键） -- `customer_id`（如有）/ `email_sha256`（如合规） -- `items[]`：sku、qty、price、category、brand、tags -- `currency`、`value` - -### 2.3 商品目录与价格库存同步（Feed / Connector） - -Nosto 的个性化推荐对“商品库质量”非常敏感，因此通常会有： - -- **全量导入**（初次接入）：把商品目录、类目、库存、价格、图片、属性标签等导入 -- **增量更新**（日常）：通过平台 webhook 或定时同步更新价格/库存/上下架 - -**商品数据的典型字段**： - -- `product_id / sku` -- `title/description` -- `image_urls` -- `category_path` -- `brand` -- `price / sale_price` -- `availability / inventory` -- `attributes/tags` - -### 2.4 电商平台连接器（Shopify / Magento / BigCommerce…） - -**典型能力**： - -- 读取/订阅：customers、orders、products、inventory -- 绑定：把“匿名行为”与“登录/下单身份”在平台侧的 customer 维度合并 -- 回写（可选）：把分群/推荐结果回写到营销工具（邮件、广告受众等） - -> 在 Shopify 生态里，Nosto 这类工具通常会同时使用：平台 API/Webhooks（业务事实）+ storefront 事件采集（浏览/加购等）。你们可对照 `docs/Shopify生态-个性化营销SaaS如何获取外部用户信息与个性化信号.md` 的“主干通道”章节。 - ---- - -## 3. 身份识别与合并（Nosto 的核心：匿名 → 已知 → 跨设备） - -### 3.1 匿名用户识别（Anonymous） - -- **匿名 ID**：由前端脚本生成并持久化（cookie/本地存储） -- **会话 ID**：用于限定“短期意图”（例如最近 30 分钟） - -### 3.2 已知用户识别（Known） - -触发点通常是： - -- 登录 -- 留资（订阅邮箱/短信） -- 下单（checkout） - -在这些节点，Nosto 会把： - -- `anonymous_id` 历史行为 -- 合并到 `customer_id/email/phone` 所对应的长期画像 - -### 3.3 跨设备关联（Cross-device） - -Nosto 类系统的常见策略（也是你们自研建议的路线）： - -- **确定性优先**：email/phone/customer_id 做主键 -- **增强匹配**（合规后）：哈希邮箱/手机号用于广告平台匹配（从而提升归因与跨设备识别） -- **概率信号**（可选）：设备指纹/网络/行为序列，但不作为第一阶段主链路 - ---- - -## 4. 外部数据打通（广告/邮件/忠诚度/评价） - -### 4.1 广告平台（Meta/Google/TikTok） - -Nosto 类产品强调的“聚合搜索与社交平台数据”，工程上通常不是“爬社交”，而是： - -- **入口串联**：从落地页 URL 获取 `fbclid/ttclid/gclid` + UTM -- **站内事件**：用前端脚本/服务端采集购买/加购/浏览 -- **平台闭环**：用平台的官方 S2S 机制回传转化（CAPI/Events API/Conversion Upload） -- **报表富化**：定时拉 campaign/ad/keyword 成本与效果，写入你们的“归因标签” - -详细的“用户匹配与外部数据打通机制”可复用你们仓库已有总结： - -- `docs/用户匹配与外部数据打通-平台官方机制提权.md` - -### 4.2 邮件/短信与 CRM（Klaviyo 等） - -常见链路： - -- Nosto → 邮件系统：把分群/推荐商品列表输出给邮件模板 -- 邮件系统 → Nosto：把 open/click/unsubscribe 等触达互动回流（用于人群质量与策略优化） - -### 4.3 忠诚度/评价（Yotpo 等） - -常见链路： - -- 订单完成触发：发评价邀请、积分发放 -- 评价/等级信号回流：作为“用户偏好/价值”的长期特征 - ---- - -## 5. 去重、延迟与一致性（工程上的“坑”） - -### 5.1 事件去重 - -- 关键事件（purchase/refund）必须可幂等： - - 以 `order_id` 为幂等键（同一订单多次回传只算一次） - - 或使用 `event_id`（保证全局唯一） - -### 5.2 延迟分层 - -- **实时层**：浏览/加购等秒级进入画像（用于推荐） -- **准实时**：订单支付可能分钟级确认（支付网关/平台事件） -- **离线层**：批量重算（商品相似度、用户聚类等） - -### 5.3 事实修正 - -- 退款/取消会“反向修正”用户价值与训练数据 -- 因此必须接入平台侧的退款/取消事件（webhook 或定时对账） - ---- - -## 6. 合规与隐私（GDPR/CCPA + Consent） - -- **同意管理**：在用户未同意前，不应写入营销/广告相关 cookie，也不应回传哈希 PII -- **数据最小化**：只采集必要字段；对 `referrer/landing_url` 做参数白名单与脱敏 -- **分租户隔离**：账号、token、数据源密钥、事件流都必须 tenant 隔离 - ---- - -## 7. 你们自研 SaaS 的可复用点（对照 Nosto） - -- **三管道模型**：行为事件 + 业务事实 + 外部信号（最关键的结构） -- **身份合并主链路**：anonymous_id → customer_id/email/phone（确定性优先） -- **广告平台闭环**：click id + S2S 回传 + 报表富化（不要依赖“平台回传用户行为”） - - diff --git a/docs/竞品参考文档/prefixbox_api.md b/docs/竞品参考文档/prefixbox_api.md deleted file mode 100644 index 81da34a..0000000 --- a/docs/竞品参考文档/prefixbox_api.md +++ /dev/null @@ -1,700 +0,0 @@ -# Prefixbox Search API 完整文档 - -*基于公开信息整理的 Prefixbox Search API 技术文档* - -*官方接口文档* -https://api-docs.prefixbox.com/#search-api - - ---- - -## 概述 - -Prefixbox Search API 是一个基于 AI 的电商搜索解决方案，提供全文搜索、向量搜索和混合搜索功能。该 API 支持自动完成、搜索建议、商品过滤、排序等核心电商搜索功能。 - -**核心特性：** -- 混合搜索（文本 + 向量 + GPT 技术） -- 自然语言查询理解 -- 动态重排序 -- 同义词管理 -- 多语言支持 - ---- - -## 1. 基础信息 - -### 1.1 API 端点 - -``` -基础 URL: https://api.prefixbox.com -版本: v1/v2 (根据集成方式不同) -``` - -### 1.2 认证方式 - -**API Key 认证** -- 在 Prefixbox API Portal 的 Profile 页面获取 Search API Key -- 所有请求必须在 Header 中包含：`Authorization: Bearer YOUR_SEARCH_API_KEY` -- 同时需要提供 Search Engine Identifier - -**Header 示例：** -```http -Authorization: Bearer pb_live_abc123xyz... -X-Search-Engine-Id: your-engine-identifier -``` - ---- - -## 2. 核心 API 端点 - -### 2.1 自动完成 API (Autocomplete API) - -**端点：** `GET /autocomplete` - -**功能：** 当用户在搜索框输入时提供实时查询建议、分类建议和商品建议。 - -**请求参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `q` | string | 是 | 用户输入的查询字符串 | -| `limit` | integer | 否 | 返回建议的最大数量 (默认: 10) | -| `type` | string | 否 | 建议类型: `all`, `queries`, `categories`, `products` (默认: all) | -| `lang` | string | 否 | ISO 639-1 语言代码 (如: en, de, fr) | - -**请求示例：** -```http -GET https://api.prefixbox.com/autocomplete?q=apple&limit=8&lang=en -Authorization: Bearer pb_live_abc123xyz... -X-Search-Engine-Id: your-engine-identifier -``` - -**响应格式：** -```json -{ - "query": "apple", - "suggestions": { - "queries": [ - {"text": "apple iphone", "count": 1250}, - {"text": "apple watch", "count": 890}, - {"text": "apple airpods", "count": 650} - ], - "categories": [ - {"id": "cat_001", "name": "Smartphones", "path": "Electronics/Mobile"}, - {"id": "cat_002", "name": "Accessories", "path": "Electronics/Accessories"} - ], - "products": [ - { - "id": "prod_12345", - "name": "Apple iPhone 15 Pro", - "image": "https://cdn.example.com/iphone15.jpg", - "price": 999.99, - "currency": "USD", - "url": "https://store.example.com/products/iphone-15-pro" - } - ] - }, - "latency_ms": 45 -} -``` - ---- - -### 2.2 搜索 API (Search API) - -**端点：** `GET /search` - -**功能：** 执行完整搜索并返回商品结果、过滤器、排序选项等。 - -**请求参数：** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `q` | string | 是 | 搜索查询字符串 | -| `page` | integer | 否 | 页码 (默认: 1) | -| `page_size` | integer | 否 | 每页商品数量 (默认: 24, 最大: 100) | -| `sort` | string | 否 | 排序方式: `relevance`, `price_asc`, `price_desc`, `newest`, `popularity` | -| `filters` | object | 否 | 过滤器对象 `{"brand": ["Apple", "Samsung"], "price_range": {"min": 500, "max": 1000}}` | -| `lang` | string | 否 | 语言代码 | -| `user_id` | string | 否 | 用户ID（用于个性化）| -| `cdp_data` | object | 否 | 客户数据平台偏好数据 | - -**请求示例：** -```http -GET https://api.prefixbox.com/search?q=running+shoes&page=1&page_size=24&sort=relevance -Authorization: Bearer pb_live_abc123xyz... -X-Search-Engine-Id: your-engine-identifier -``` - -**完整带过滤器的请求：** -```http -GET https://api.prefixbox.com/search?q=running+shoes&filters={"brand":["Nike","Adidas"],"price_range":{"min":50,"max":200},"size":["8","9","10"]} -Authorization: Bearer pb_live_abc123xyz... -X-Search-Engine-Id: your-engine-identifier -``` - -**响应格式：** -```json -{ - "search_id": "search_abc123xyz789", - "query": "running shoes", - "total_results": 1456, - "page": 1, - "page_size": 24, - "total_pages": 61, - "latency_ms": 120, - "products": [ - { - "id": "prod_67890", - "name": "Nike Air Zoom Pegasus", - "description": "Responsive running shoes with Zoom Air cushioning", - "image": "https://cdn.example.com/nike-pegasus.jpg", - "price": 129.99, - "original_price": 159.99, - "currency": "USD", - "url": "https://store.example.com/products/nike-air-zoom-pegasus", - "availability": "in_stock", - "brand": "Nike", - "category": "Running Shoes", - "score": 0.987 - } - ], - "filters": [ - { - "name": "brand", - "type": "multiselect", - "values": [ - {"value": "Nike", "count": 456}, - {"value": "Adidas", "count": 389}, - {"value": "Asics", "count": 234} - ] - }, - { - "name": "price", - "type": "range", - "min": 29.99, - "max": 299.99 - }, - { - "name": "size", - "type": "multiselect", - "values": [ - {"value": "7", "count": 156}, - {"value": "8", "count": 234}, - {"value": "9", "count": 289} - ] - } - ], - "sort_options": [ - {"value": "relevance", "label": "Relevance"}, - {"value": "price_asc", "label": "Price: Low to High"}, - {"value": "price_desc", "label": "Price: High to Low"}, - {"value": "newest", "label": "Newest First"}, - {"value": "popularity", "label": "Most Popular"} - ], - "related_keywords": ["trail running", "marathon shoes", "lightweight trainers"], - "related_categories": [ - {"id": "cat_sports", "name": "Sports & Outdoors"}, - {"id": "cat_footwear", "name": "Footwear"} - ], - "personalized": false, - "ai_reranking": true -} -``` - ---- - -### 2.3 商品详情 API (Product Details API) - -**端点：** `GET /products/{product_id}` - -**功能：** 获取单个商品的详细信息。 - -**请求示例：** -```http -GET https://api.prefixbox.com/products/prod_67890 -Authorization: Bearer pb_live_abc123xyz... -X-Search-Engine-Id: your-engine-identifier -``` - -**响应格式：** -```json -{ - "id": "prod_67890", - "name": "Nike Air Zoom Pegasus", - "description": "Responsive running shoes with Zoom Air cushioning", - "long_description": "Detailed product description...", - "images": [ - "https://cdn.example.com/nike-pegasus-1.jpg", - "https://cdn.example.com/nike-pegasus-2.jpg" - ], - "price": 129.99, - "original_price": 159.99, - "currency": "USD", - "url": "https://store.example.com/products/nike-air-zoom-pegasus", - "availability": "in_stock", - "stock_quantity": 45, - "brand": "Nike", - "category": "Running Shoes", - "attributes": { - "color": ["Black", "White", "Blue"], - "size": ["7", "8", "9", "10", "11", "12"], - "material": "Mesh and Rubber", - "weight": "280g" - }, - "reviews": { - "average_rating": 4.5, - "count": 234 - }, - "tags": ["marathon", "neutral", "cushioned"] -} -``` - ---- - -### 2.4 分类页面 API (Collection API) - -**端点：** `GET /collections/{collection_id}` - -**功能：** 获取分类页面的商品列表。 - -**请求参数：** - -| 参数 | 类型 | 说明 | -|------|------|------| -| `collection_id` | string | 分类ID | -| `page` | integer | 页码 | -| `page_size` | integer | 每页数量 | -| `sort` | string | 排序方式 | -| `filters` | object | 过滤器 | - -**响应格式：** 与 Search API 类似，但返回的是特定分类的商品 - ---- - -## 3. 高级功能 API - -### 3.1 个性化搜索 API - -**端点：** `GET /search/personalized` - -**功能：** 基于用户偏好数据返回个性化排序结果。 - -**请求参数：** -```json -{ - "q": "running shoes", - "user_id": "user_12345", - "cdp_data": { - "preferred_brands": ["Nike", "Adidas"], - "preferred_size": "9", - "preferred_color": "Black", - "past_purchases": ["prod_111", "prod_222"] - } -} -``` - ---- - -### 3.2 AI 重排序 API - -**端点：** `POST /search/rerank` - -**功能：** 基于用户行为数据动态重排搜索结果。 - -**请求参数：** -```json -{ - "search_id": "search_abc123xyz789", - "user_interactions": { - "clicks": ["prod_67890", "prod_67891"], - "hover_time_ms": 2500, - "previous_searches": ["trail running"] - } -} -``` - ---- - -## 4. 推荐 API (AI Recommend) - -### 4.1 相关产品推荐 - -**端点：** `GET /recommendations/related` - -**请求参数：** -```http -GET /recommendations/related?product_id=prod_67890&limit=6 -``` - -**响应格式：** -```json -{ - "product_id": "prod_67890", - "recommendations": [ - { - "id": "prod_67891", - "name": "Nike Dri-FIT Running Socks", - "reason": "Frequently bought together" - }, - { - "id": "prod_67892", - "name": "Nike Running Cap", - "reason": "Similar category" - } - ] -} -``` - ---- - -### 4.2 热门商品推荐 - -**端点：** `GET /recommendations/trending` - -```http -GET /recommendations/trending?category=running&limit=8 -``` - ---- - -## 5. 分析追踪 API - -### 5.1 搜索事件追踪 - -**端点：** `POST /analytics/search-event` - -**功能：** 追踪用户搜索行为以优化搜索相关性。 - -**事件类型：** -- `search_impression` - 搜索结果展示 -- `search_click` - 用户点击结果 -- `search_add_to_cart` - 添加商品到购物车 -- `search_purchase` - 完成购买 - -**请求示例：** -```json -{ - "search_id": "search_abc123xyz789", - "event_type": "search_click", - "user_id": "user_12345", - "product_id": "prod_67890", - "position": 1, - "timestamp": "2025-01-15T10:30:00Z" -} -``` - ---- - -## 6. 实时目录更新 API - -**端点：** `POST /catalog/update` - -**功能：** 实时更新商品目录数据。 - -**请求格式：** -```json -{ - "updates": [ - { - "product_id": "prod_67890", - "field": "stock_quantity", - "value": 23, - "action": "update" - }, - { - "product_id": "prod_67891", - "action": "delete" - } - ] -} -``` - ---- - -## 7. 错误处理 - -### 7.1 HTTP 状态码 - -| 状态码 | 说明 | -|--------|------| -| `200` | 请求成功 | -| `400` | 请求参数错误 | -| `401` | 认证失败 - API Key 无效或缺失 | -| `403` | 权限不足 | -| `404` | 资源未找到 | -| `429` | 请求频率限制 | -| `500` | 服务器内部错误 | - -### 7.2 错误响应格式 - -```json -{ - "error": { - "code": "INVALID_API_KEY", - "message": "The provided API key is invalid or expired.", - "status": 401, - "request_id": "req_123456789" - } -} -``` - ---- - -## 8. 代码集成示例 - -### 8.1 JavaScript/Frontend 集成 - -```javascript -// 初始化 Prefixbox 客户端 -const prefixbox = new PrefixboxClient({ - apiKey: 'pb_live_abc123xyz...', - searchEngineId: 'your-engine-identifier', - language: 'en' -}); - -// 自动完成 -const suggestions = await prefixbox.autocomplete({ - query: 'run', - limit: 8 -}); - -// 搜索 -const searchResults = await prefixbox.search({ - query: 'running shoes', - page: 1, - pageSize: 24, - filters: { - brand: ['Nike', 'Adidas'], - priceRange: { min: 50, max: 200 } - } -}); - -// 追踪事件 -prefixbox.trackEvent('search_click', { - searchId: searchResults.searchId, - productId: 'prod_67890', - position: 1 -}); -``` - -### 8.2 cURL 示例 - -```bash -# 自动完成 -curl -X GET "https://api.prefixbox.com/autocomplete?q=apple&limit=5" \ - -H "Authorization: Bearer pb_live_abc123xyz..." \ - -H "X-Search-Engine-Id: your-engine-identifier" - -# 搜索 -curl -X GET "https://api.prefixbox.com/search?q=laptop&page=1&page_size=24" \ - -H "Authorization: Bearer pb_live_abc123xyz..." \ - -H "X-Search-Engine-Id: your-engine-identifier" -``` - -### 8.3 Python 集成示例 - -```python -import requests - -class PrefixboxClient: - def __init__(self, api_key, search_engine_id): - self.base_url = "https://api.prefixbox.com" - self.headers = { - "Authorization": f"Bearer {api_key}", - "X-Search-Engine-Id": search_engine_id, - "Content-Type": "application/json" - } - - def autocomplete(self, query, limit=10): - endpoint = f"{self.base_url}/autocomplete" - params = {"q": query, "limit": limit} - response = requests.get(endpoint, headers=self.headers, params=params) - return response.json() - - def search(self, query, page=1, page_size=24, filters=None): - endpoint = f"{self.base_url}/search" - params = { - "q": query, - "page": page, - "page_size": page_size - } - if filters: - params["filters"] = filters - - response = requests.get(endpoint, headers=self.headers, params=params) - return response.json() - -# 使用示例 -client = PrefixboxClient( - api_key="pb_live_abc123xyz...", - search_engine_id="your-engine-identifier" -) - -# 执行搜索 -results = client.search( - query="wireless headphones", - filters={"brand": ["Sony", "Bose"], "price_range": {"min": 100, "max": 300}} -) - -print(f"找到 {results['total_results']} 个商品") -for product in results['products']: - print(f"- {product['name']}: ${product['price']}") -``` - ---- - -## 9. SDK 和库 - -Prefixbox 提供以下官方 SDK： - -- **JavaScript SDK**: `npm install @prefixbox/search-js` -- **React SDK**: `npm install @prefixbox/react-search` -- **Python SDK**: `pip install prefixbox-search` -- **PHP SDK**: `composer require prefixbox/search` - ---- - -## 10. 集成方式 - -### 10.1 API 集成 - -**适用场景：** 需要完全自定义 UI 和用户体验 - -**客户职责：** -- 提供商品 Feed URL -- 实现与 Prefixbox API 的通信 -- 实现搜索 UX 界面 -- 实现用户行为追踪 -- Bug 修复和发布 - -**Prefixbox 职责：** -- 在 Admin Portal 配置搜索模块 -- 定制功能需求 -- 测试和报告 Bug -- 运行 A/B 测试 - -### 10.2 前端 JavaScript 集成 - -**适用场景：** 快速部署，最小化开发工作量 - -**客户职责：** -- 提供带 header/footer 的空搜索结果页 -- 提供商品 Feed URL -- 在网站中插入 Prefixbox JavaScript - -**Prefixbox 职责：** -- 配置搜索模块 -- 定制外观和功能 -- 测试、预览和修复 Bug -- 发布到生产环境 - ---- - -## 11. 商品 Feed 格式 - -Prefixbox 要求提供兼容的商品 Feed： - -**必需字段：** -- `id` - 商品唯一标识符 -- `name` - 商品名称 -- `url` - 商品页面 URL -- `price` - 价格 -- `currency` - 货币代码 -- `availability` - 库存状态 - -**推荐字段：** -- `description` - 商品描述 -- `image` - 商品图片 URL -- `brand` - 品牌 -- `category` - 分类 -- `attributes` - 商品属性（颜色、尺寸等） -- `created_at` - 创建日期 -- `popularity_score` - 热门度分数 - -**支持格式：** JSON, XML, CSV - ---- - -## 12. 限制和配额 - -### 12.1 API 请求限制 - -| 套餐 | 月请求配额 | 每分钟限制 | -|------|-----------|-----------| -| Starter | 20,000 | 100 | -| Growth | 200,000 | 500 | -| Grow+ | 600,000-900,000 | 1,000 | -| Enterprise | 自定义 | 自定义 | - -### 12.2 什么算作 API 请求？ - -- **自动完成：** 每个字符输入 = 1 次请求 -- **搜索：** 每次搜索 = 1 次请求 -- **过滤/排序：** 每次操作 = 1 次请求 -- **分页：** 每次翻页 = 1 次请求 - -**示例：** 用户输入 "apple"（6 次自动完成请求）+ 执行搜索（1 次）+ 过滤（1 次）+ 翻页（1 次）= **共 9 次 API 请求** - ---- - -## 13. 支持和资源 - -### 13.1 官方资源 - -- **API 文档门户：** https://api-docs.prefixbox.com -- **开发者中心：** https://developers.prefixbox.com -- **技术文档：** https://www.prefixbox.com/en-us/technical -- **集成指南：** https://www.prefixbox.com/en-us/technical/integration - -### 13.2 支持级别 - -| 支持级别 | 可用套餐 | 响应时间 | -|---------|---------|---------| -| 标准支持 | Starter, Growth | 24-48 小时 | -| 高级支持 | Grow+ | 4 小时 | -| 专属支持 | Enterprise | 1 小时 | - ---- - -## 14. 最佳实践 - -### 14.1 性能优化 - -1. **缓存自动完成结果** - 减少重复请求 -2. **延迟搜索** - 用户停止输入 300ms 后再发送请求 -3. **分页加载** - 使用无限滚动或分页 -4. **图片优化** - 使用 CDN 和适当尺寸的图片 - -### 14.2 提升搜索相关性 - -1. **配置同义词** - 连接不同词汇（如 "sneakers" = "trainers"） -2. **设置字段权重** - 提升重要字段的权重（如 name > description） -3. **使用 A/B 测试** - 测试不同配置对转化率的影响 -4. **分析零结果搜索** - 识别缺失商品或查询问题 - -### 14.3 用户体验 - -1. **显示搜索建议** - 帮助用户快速找到相关查询 -2. **保留搜索上下文** - 支持返回搜索结果 -3. **移动端优化** - 确保触摸友好的界面 -4. **加载状态** - 提供清晰的加载指示 - ---- - -## 15. 常见问题 - -### Q: API 返回 429 错误怎么办？ -A: 表示达到速率限制。实现指数退避重试策略，或升级到更高配额的套餐。 - -### Q: 如何处理多语言搜索？ -A: 在请求中使用 `lang` 参数，并确保商品 Feed 包含翻译内容。 - -### Q: 可以自定义搜索算法吗？ -A: 可以在 Prefixbox Admin Portal 中调整字段权重和同义词规则。 - -### Q: 支持语音搜索吗？ -A: 是的，Prefixbox AI Agent 支持自然语言查询和语音搜索集成。 - -### Q: 如何集成到移动应用？ -A: 通过 API 集成方式，使用 iOS/Android 原生开发或 React Native 调用 REST API。 diff --git a/docs/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md b/docs/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md deleted file mode 100644 index 3062611..0000000 --- a/docs/竞品参考文档/电商个性化推荐 SaaS 技术方案：数据获取与打通.md +++ /dev/null @@ -1,204 +0,0 @@ -# 电商个性化推荐 SaaS 技术方案：数据获取与打通 - -## 1. 引言 - -本技术方案旨在阐述如何构建一个电商个性化推荐 SaaS 平台，重点聚焦于**全渠道数据获取、数据整合与打通**的核心技术实现。我们将借鉴 Nosto 等行业领先者的实践经验，结合当前主流技术栈，设计一套可扩展、高可用且符合数据隐私规范的系统架构。 - -## 2. 核心架构概览 - -个性化推荐 SaaS 平台的核心在于高效地收集、整合和处理来自不同渠道的用户行为数据与业务数据，并在此基础上构建统一的客户视图，为个性化推荐提供坚实的数据基础。以下是整体架构的概览图： - -![架构概览图](https://private-us-east-1.manuscdn.com/sessionFile/MPBkQjAwYEPDQuw5oSNkba/sandbox/owNsnbnP40DtzKCFvilk2L-images_1767771038719_na1fn_L2hvbWUvdWJ1bnR1L2FyY2hpdGVjdHVyZV9kaWFncmFt.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9wcml2YXRlLXVzLWVhc3QtMS5tYW51c2Nkbi5jb20vc2Vzc2lvbkZpbGUvTVBCa1FqQXdZRVBEUXV3NW9TTmtiYS9zYW5kYm94L293TnNuYm5QNDBEdHpLQ0Z2aWxrMkwtaW1hZ2VzXzE3Njc3NzEwMzg3MTlfbmExZm5fTDJodmJXVXZkV0oxYm5SMUwyRnlZMmhwZEdWamRIVnlaVjlrYVdGbmNtRnQucG5nIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzk4NzYxNjAwfX19XX0_&Key-Pair-Id=K2HSFNDJXOU9YS&Signature=FOl36NdZP1NUxEmHSK-TFKC~zEvwPmCzWVcDQVxKtQIzYks0awx2i~PJtck2gywvi9jrDlCpGb49tbzEFEzT6omZ84EDJ4O930Y2mGTFiZcWZDKQY617u9zg3tVh39c6tczcsy47b~YhrTwbks8zANpI9GGdQLqhG0fRM2hkLM1AhJz3bP2qHNjgpsY7cqYDzHgtsNo0qaZVCysAxDFrKLPjXxHfU-udrbJjQ~RZs9mIHsEwP5a3WvHPpxBZMeq4b0Rvi0nmnxITsOwbQrEiovu5X8WdOwtAP-waLewGyFVlAhROuP02hw3BVcwO3Dwq2CVgIbXQru4Q4EDvocarAQ__) - -## 3. 数据采集层：多源异构数据接入 - -数据采集是构建个性化推荐系统的第一步，也是最关键的一步。我们需要建立一套灵活、实时且可靠的数据采集机制，覆盖用户在电商旅程中的所有触点。 - -### 3.1 网站与移动应用行为数据采集 - -* **网站行为数据**：通过 **JavaScript SDK (Pixel)** 部署在电商网站前端，实时捕获用户的页面浏览、点击、加购、收藏、搜索、购买等行为。每个会话通过 `session_id` 或 `cookie_id` 进行标识。SDK 应支持异步加载，避免影响网站性能。 -* **移动应用数据**：通过 **原生 SDK (iOS/Android)** 嵌入到移动应用中，采集与网站类似的用户行为数据。为实现跨设备追踪，移动 SDK 需与网站 SDK 共享用户 ID 机制。 - -**技术实现建议**： -* **消息队列**：采用 **Apache Kafka** 或 **RabbitMQ** 作为数据接入层，处理每秒数十万级别的实时事件流，确保数据不丢失、高吞吐量和低延迟 [1]。 -* **数据格式**：统一采用 JSON 或 Protobuf 格式封装事件数据，包含 `event_type`、`user_id` (如果已知)、`anonymous_id`、`session_id`、`product_id`、`timestamp`、`device_info`、`geo_location` 等关键字段。 - -### 3.2 第三方平台数据接入 - -电商生态系统往往涉及多个外部平台，如社交媒体、广告平台、营销自动化工具等。通过 **Server-to-Server (S2S) API 集成** 是实现这些数据打通的关键，而非简单的客户端 SDK 采集或数据爬取。 - -* **社交媒体平台 (如 Meta/Facebook/Instagram)**： - * **OAuth 2.0 授权**：商家通过 OAuth 2.0 流程授权 SaaS 平台访问其 Meta 商业账户的 API 权限（如 `ads_management`, `ads_read`, `business_management`）。SaaS 平台获取长期访问令牌，用于后续的 API 调用 [2]。 - * **Meta Conversions API (CAPI)**：SaaS 平台作为 Meta 的合作伙伴，通过 CAPI 将服务器端的转化事件（如购买、加购）直接发送给 Meta，弥补浏览器端 Pixel 追踪的不足，提高广告归因的准确性 [3]。这需要服务器到服务器的直接通信，而非通过用户浏览器。 -* **广告平台 (如 Google Ads)**： - * **Google Ads API**：通过 API 获取广告投放数据、点击数据和转化数据。同样，需要商家授权 SaaS 平台访问其 Google Ads 账户 [4]。 - * **Server-Side Tagging**：利用 Google Tag Manager (GTM) 的服务器端容器，将网站事件数据发送到 SaaS 平台的服务器，再由 SaaS 平台转发给 Google Ads，实现更可靠的追踪 [5]。 -* **其他第三方平台 (如 Shopify Flow, LoyaltyLion, Yotpo)**： - * **Webhook 机制**：通过配置 Webhook，当第三方平台发生特定事件（如订单状态变更、会员积分变动、用户评论）时，实时将数据推送到 SaaS 平台的数据接收接口。 - * **API 定时拉取**：对于不支持 Webhook 或需要批量同步的数据，通过定时任务调用第三方平台的 API 进行数据拉取。 - -**关键技术特征**： -* **双向 S2S 架构**：数据直接在商家服务器 → SaaS 平台服务器 → 外部平台服务器之间传输，无需中间人。 -* **实时 + 批量混合**：支持实时事件转发（毫秒级）和定时批量同步（小时级）。 -* **去重机制**：通过 `event_id` 和 `session_id` 避免客户端与服务端事件重复。 - -### 3.3 离线数据导入 - -* **CRM/POS 系统数据**：支持通过 SFTP 文件传输（CSV/JSON 格式）或实时 API 推送的方式，批量导入客户关系管理 (CRM) 系统和销售终端 (POS) 系统中的客户信息、订单历史、会员等级等数据。 -* **CDP 集成**：支持 Segment、mParticle 等标准 CDP 的数据格式，方便商家将已有的 CDP 数据导入。 - -## 4. 身份识别与统一：构建 Identity Graph - -全渠道数据整合的核心挑战之一是**用户身份识别与统一**。不同渠道的用户行为可能由同一个用户产生，但却拥有不同的标识符（如网站 Cookie ID、App 设备 ID、邮箱、手机号）。构建 **Identity Graph (身份图谱)** 是解决这一问题的关键。 - -### 4.1 身份图谱的核心逻辑 - -Identity Graph 旨在将一个用户的不同标识符关联起来，形成一个统一的客户视图 (Customer 360)。 - -| 标识符类型 | 描述 | 示例 | -| :--------------- | :--------------------------------------- | :--------------------------------------- | -| **匿名 ID** | 设备级标识，如 `2c.cId cookie` 值、设备指纹 | `cookie_value_xyz`、`web_1920x1080_chrome_mac` | -| **已知 ID** | 登录用户标识，如 `user_id`、邮箱、手机号 | `user_12345`、`user@example.com`、`+86-138****1234` | -| **关联关系** | 不同 ID 之间的连接关系 | `user_12345` 关联 `cookie_value_xyz` | - -### 4.2 关键技术与匹配策略 - -* **确定性匹配 (Deterministic Matching)**： - * 基于强标识符进行匹配，准确率高。例如，用户登录时，将当前匿名会话的 `anonymous_id` 与其 `user_id` 进行关联。 - * 其他确定性匹配场景包括邮箱订阅、手机号绑定、会员卡号等。 - * **技术实现**：维护一个 ID 映射表，存储 `anonymous_id` 到 `user_id` 的映射关系，并支持实时更新。 -* **概率性匹配 (Probabilistic Matching)**： - * 当缺乏强标识符时，通过算法推测不同匿名行为是否属于同一用户。例如，基于设备指纹 (Device Fingerprint)、行为模式、IP 地址、地理位置等信息进行匹配 [6]。 - * **设备指纹**：结合浏览器类型、操作系统、屏幕分辨率、插件列表、字体等信息生成设备的唯一标识。可集成第三方库如 FingerprintJS。 - * **行为模式**：分析用户在不同设备上的浏览路径、购买偏好、时间规律等，通过机器学习模型计算相似度。 - * **技术实现**： - * **图数据库 (如 Neo4j)**：存储 ID 之间的关联关系，方便进行复杂的关系查询和图算法分析，发现潜在的概率性匹配 [7]。 - * **机器学习模型**：训练分类模型（如逻辑回归、随机森林）来预测不同匿名 ID 属于同一用户的概率。 -* **实时 ID 合并**：当用户登录或提供新的身份信息时，系统应立即合并其历史匿名行为数据，更新用户画像，确保推荐的实时性和准确性。 - -## 5. 数据整合与处理：统一客户数据资产 (CDP) - -将采集到的多源数据和统一身份后的数据进行整合、清洗、转换，最终形成一个统一的客户数据平台 (Customer Data Platform, CDP)，是为个性化推荐提供数据支撑的关键。 - -### 5.1 Lambda 架构与实时流处理 - -为满足“每秒数十万次实时请求”和毫秒级延迟更新用户画像的需求，系统应采用 **Lambda 架构**，结合实时层和批处理层 [8]。 - -* **实时层**： - * **技术栈**：**Apache Flink** 或 **Spark Streaming**。 - * **功能**：处理 Kafka 消息队列中的实时行为流，进行数据清洗、格式转换、实时聚合、特征提取，并毫秒级延迟更新用户画像。 - * **输出**：实时更新的用户画像数据存储到 Redis 等低延迟存储中。 -* **批处理层**： - * **技术栈**：**Apache Spark** 或 **Hadoop MapReduce**。 - * **功能**：每日或定期处理全量历史数据，进行更复杂的离线计算，如用户聚类、商品相似度计算、模型训练、数据修正和补充实时计算结果。 - * **输出**：离线计算结果存储到 HDFS/S3 等分布式存储，并同步到 CDP。 - -### 5.2 CDP 核心数据模型 - -CDP 旨在构建一个全面的客户 360 度视图，包含以下核心数据域： - -| 数据域 | 存储内容 | 典型技术组件 | -| :----------- | :--------------------------------------- | :----------------------- | -| **行为事件** | 点击、浏览、加购、购买等原始事件 | Kafka + Flink | -| **用户属性** | 人口统计、会员等级、RFM 标签、偏好向量 | Redis + PostgreSQL | -| **产品目录** | SKU、价格、库存、类目、标签等商品元数据 | Elasticsearch | -| **场景上下文** | 时间、设备、地理位置、来源渠道 | MongoDB | -| **关系网络** | 用户相似度、商品共现、ID 关联关系 | Neo4j 图数据库 | - -### 5.3 数据存储策略 - -根据数据的访问频率和时效性，采用分层存储策略： - -* **热数据**：用户最近的活跃行为（如最近 50 个行为）存储在 **Redis** 集群中，设置较短的 TTL (Time-To-Live)，支持毫秒级快速读写。 -* **温数据**：近 30 天的行为数据存储在 **Cassandra** 或 **ClickHouse** 等分布式列式数据库中，支持快速查询和聚合分析。 -* **冷数据**：全量历史数据存储在 **S3/HDFS** 等对象存储或分布式文件系统中，用于离线训练和长期归档。 - -## 6. SaaS 平台化设计：多租户与数据安全 - -作为一个 SaaS 平台，多租户架构设计至关重要，需要确保不同商家之间的数据隔离、资源隔离和安全性。 - -### 6.1 多租户隔离策略 - -* **数据隔离**： - * **独立数据库 (Database-per-Tenant)**：为每个商家分配独立的数据库实例，提供最强的数据隔离性，但成本较高，管理复杂 [9]。 - * **独立 Schema (Schema-per-Tenant)**：在共享数据库中为每个商家创建独立的 Schema，数据隔离性良好，成本适中 [9]。 - * **共享数据库，通过 Tenant ID 隔离 (Shared Database with Tenant ID)**：所有商家数据存储在同一个数据库中，通过在每张表中添加 `tenant_id` 字段进行逻辑隔离。实现简单，成本最低，但需要严格的应用程序逻辑控制数据访问 [9]。 - * **建议**：对于核心敏感数据（如用户画像、行为事件），可采用独立 Schema 或独立数据库；对于公共数据（如商品目录模板），可采用共享数据库加 `tenant_id` 隔离。在 Kafka 消息队列中，可为每个租户创建独立 Topic 或使用 `tenant_id` 作为消息 Key 进行分区。 -* **资源隔离**： - * **Kubernetes 命名空间 (Namespace)**：在 Kubernetes 集群中为每个商家创建独立的命名空间，通过资源配额 (Resource Quotas) 限制 CPU、内存等资源使用，防止“邻居干扰”问题 [10]。 - * **容器化部署**：将各个服务（数据采集、流处理、API 服务等）容器化，通过 Docker 和 Kubernetes 进行部署和管理。 -* **API 隔离**：为每个商家提供独立的 `accountID` 和 API Key，确保 API 调用的安全性和隔离性。 - -### 6.2 数据安全与合规 - -* **数据加密**：所有敏感数据（如用户 PII、支付信息）在传输和存储过程中必须进行加密。使用 TLS/SSL 保护数据传输，使用 AES-256 等算法加密静态数据。 -* **访问控制**：实施严格的基于角色的访问控制 (RBAC)，确保只有授权用户才能访问特定数据和功能。 -* **隐私合规**： - * **GDPR (通用数据保护条例)** 和 **CCPA (加州消费者隐私法案)**：确保数据采集、存储、处理和共享符合 GDPR 和 CCPA 等隐私法规的要求 [11]。 - * **用户数据删除**：提供用户数据删除功能，支持用户行使“被遗忘权”。 - * **数据最小化**：只收集和存储必要的、与业务目的相关的数据。 - * **透明度**：向用户清晰说明数据收集和使用政策。 - -## 7. 实施路线图 (数据获取与打通阶段) - -### 7.1 第一阶段：MVP (数据采集与身份识别) - -* **基础设施搭建**： - * 消息队列：Kafka (3 节点集群) - * 流处理：Flink on Kubernetes - * 缓存：Redis Cluster (6 节点) - * 数据库：PostgreSQL (用户数据) + Elasticsearch (商品目录) - * API 网关：Kong/AWS API Gateway -* **核心功能实现**： - * **JavaScript SDK**：页面埋点、Cookie 管理、行为上报。 - * **身份服务**：匿名 ID 生成、登录态关联、ID 映射表。 - * **数据接收 API**：接收网站/APP SDK 上报的事件数据，写入 Kafka。 - * **管理后台**：商家注册、API Key 管理、数据源配置。 -* **数据模型设计**： - * `user_events` 表：存储原始用户行为事件。 - * `user_identity_map` 表：存储匿名 ID 与已知 ID 的映射关系。 - -### 7.2 第二阶段：全渠道整合与 CDP 建设 - -* **扩展数据源**： - * **移动端 SDK**：iOS/Android 埋点采集。 - * **CRM 对接**：Salesforce、HubSpot API 集成。 - * **营销平台对接**：Klavyio、Mailchimp 获取邮件互动数据。 - * **广告平台 S2S 集成**：Meta CAPI、Google Ads API/Server-Side Tagging。 -* **增强身份识别**： - * **设备指纹库**：集成 FingerprintJS/Thumbor。 - * **图谱算法**：使用 Neo4j 存储 ID 关联关系，实现概率匹配。 - * **实时 ID 合并引擎**：确保用户身份实时统一。 -* **CDP 建设**： - * **实时用户画像**：Flink 处理实时流，更新 Redis 中的用户画像。 - * **统一客户数据模型**：设计并实现 CDP 核心数据模型，整合行为、属性、产品、场景数据。 - * **数据存储分层**：Redis (热数据)、Cassandra (温数据)、S3/HDFS (冷数据)。 - -## 8. 关键技术挑战与应对方案 - -| 挑战 | 应对方案 | -| :------------- | :------------------------------------------- | -| **数据延迟** | Flink 实时流处理，Redis 缓存热数据，P99 延迟 < 200ms | -| **ID 关联准确率** | 确定性 + 概率性匹配，持续学习优化，初期 95% 准确率，通过反馈数据迭代 | -| **商品库同步** | 支持增量同步 + 全量校对，延迟 < 1 分钟 | -| **多租户数据隔离** | 独立 Schema/数据库 + Tenant ID 逻辑隔离，Kubernetes 资源配额 | -| **数据安全合规** | 数据加密、RBAC、GDPR/CCPA 合规，支持用户数据删除 | -| **系统稳定性** | 熔断、限流、降级三件套，多云部署，99.9% 可用性 | - -## 9. 总结 - -本方案详细阐述了构建电商个性化推荐 SaaS 平台在**数据获取与打通**方面的技术实现路径。通过建立强大的数据采集层、智能的身份识别服务、高效的数据整合处理机制以及安全的多租户架构，我们将能够为商家提供一个稳定、可靠且功能强大的个性化推荐基础平台，助力其实现业务增长。 - -## 10. 参考文献 - -[1] Apache Kafka. [https://kafka.apache.org/](https://kafka.apache.org/) -[2] Meta for Developers - OAuth 2.0. [https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/) -[3] Meta for Developers - Conversions API. [https://developers.facebook.com/docs/marketing-api/conversions-api/](https://developers.facebook.com/docs/marketing-api/conversions-api/) -[4] Google Ads API. [https://developers.google.com/google-ads/api/docs/start](https://developers.google.com/google-ads/api/docs/start) -[5] Google Tag Manager - Server-side tagging. [https://developers.google.com/tag-platform/tag-manager/server-side/intro](https://developers.google.com/tag-platform/tag-manager/server-side/intro) -[6] Identity Resolution: Unifying User Profiles. [https://www.okta.com/identity-101/identity-resolution/](https://www.okta.com/identity-101/identity-resolution/) -[7] Neo4j Graph Database. [https://neo4j.com/](https://neo4j.com/) -[8] Lambda Architecture. [https://en.wikipedia.org/wiki/Lambda_architecture](https://en.wikipedia.org/wiki/Lambda_architecture) -[9] Data Isolation and Sharding Architectures for Multi-Tenant Systems. [https://medium.com/@justhamade/data-isolation-and-sharding-architectures-for-multi-tenant-systems-20584ae2bc31](https://medium.com/@justhamade/data-isolation-and-sharding-architectures-for-multi-tenant-systems-20584ae2bc31) -[10] Kubernetes Namespaces. [https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -[11] GDPR for SaaS: 8 Steps to Ensure Compliance. [https://www.cookieyes.com/blog/gdpr-for-saas/](https://www.cookieyes.com/blog/gdpr-for-saas/) -- libgit2 0.21.2