合作方 Postback 集成校验
受众： 在联盟后台配置 postback 的人，以及确认配置已就绪的 AM 或 BD。请在第一个广告系列上线之前跑一遍本页。
Postback 是发往 https://mmp.revosurge.com 的普通 HTTP GET 调用，所有内容都放在查询串里。
规则分两档
必需规则会阻止上线。建议规则不会，但每一条都有具体的代价——通常是归因质量，或对账能力。
规则 ID（PB-R-01、PB-O-01…）是稳定的。请在工单和发给合作方的邮件中引用它们。
Postback 的失败是刻意静默的
RevoSurge 绝不会因为负载问题返回 4xx。一条没有可用身份标识的 postback 会返回 200 {"status":"ignored"}——你的后台会把它记为成功，而这笔转化就此消失。本页大部分内容都是因为这一个行为而存在的。
必需规则
| ID | 规则 | 失败会导致什么 |
|---|---|---|
PB-R-01 | 每次调用都带上正确的 k | 403。什么都不会被记录。 |
PB-R-02 | 端点路径与事件相符——事件类型由路径决定 | event 宏只作交叉核对记录，绝不用于判定类型。把充值发到注册路径，它就永远是一次注册。 |
PB-R-03 | click_id 与 user_id 至少有一个 | 200 {"status":"ignored"}。在你的日志里看起来是成功，但这笔转化并不存在。 |
PB-R-04 | click_id 或 user_id 中没有未替换的宏 | 字面量 {sub1} 会让整条 postback 被丢弃。在其他字段中则只损失该字段。 |
PB-R-05 | 首次充值发到 /first-deposit，之后的充值发到 /repeat-deposit | 首充（FTD）数会双向出错，而 FTD 通常正是广告系列的出价目标。 |
PB-R-06 | ts 是 unix 毫秒，不是秒 | 秒级值会被自动纠正，并作为契约偏离上报。不会有任何失败，但你依赖的是我们的纠正，而不是发送你真正想表达的值——而且告警会落到你的客户经理那里，而不是你。 |
PB-R-07 | /first-deposit、/repeat-deposit 和 /revenue 都发送 amount，且符号正确（/registration 与 /app-launch 不带金额） | 没有可报告的收入，也无从计算 ROAS。 |
PB-R-08 | event_id 全局唯一、稳定，并在重试时原样重复 | 没有它，去重会退回到 txid，再退回到查询串哈希。任何字段顺序变动的重试都会变成第二笔转化。 |
PB-R-09 | 503 要重试；200 和 403 不重试 | 503 表示写入未被确认——除非你重发，这笔转化就丢了。缺少 event_id 时重试 200 有重复计数的风险。 |
PB-R-10 | 注册的生产 URL 中不含 dryrun | 每条 postback 都只返回判定结果，什么都不记录。 |
PB-R-11 | user_id 与你在 Web 追踪器和 S2S 中使用的标识相同 | 同一玩家变成两份档案。充值无法关联到带来它的那次点击。 |
PB-R-12 | Postback 从你的后台服务端触发，而不是从浏览器 | k 密钥以明文出现在 URL 中——浏览器触发的 postback 会把它暴露在页面源码里。客户端调用还会被广告拦截器拦掉，并在刷新时重复触发。 |
建议规则
| ID | 规则 | 代价是什么 |
|---|---|---|
PB-O-01 | 发送 ctx | click_id 缺失或过期时没有兜底归因。 |
PB-O-02 | 发送 txid 作为第二去重键 | 一旦 event_id 缺失，去重就会降级为查询串哈希，这很脆弱。 |
PB-O-03 | 用真实值填写 hash_id / hash_name 和 source_id / source_name | 没有按链接或流量来源的细分。广告系列表现不佳时，你无法分辨是哪个投放位带来了这些充值。 |
PB-O-04 | 发送 country | 地域报表更弱；我们只能退回到推断。 |
PB-O-05 | 把你自己的事件类型宏作为 event 发送 | 失去能发现端点用错（PB-R-02）的交叉核对。 |
PB-O-06 | 在你知道时声明 is_new_customer 和 first_deposit_ts | 我们无法用自己的首充判定来印证你的首充分类。 |
PB-O-07 | 若你采用分摊归因模型，声明 attribution_share | 归因会被当作全额归因处理，同时高估 RevoSurge 和你自己的贡献。 |
必需项修复方式
PB-R-01 —— 密钥错误或缺失
修复： 在 URL 中加上 k=<your postback key>。密钥在对接时下发——如果你没有，请向你的客户经理索取。
请把它当作共享密钥：它只放在你后台保存的服务端 postback URL 中，绝不能出现在玩家浏览器能看到的任何地方。
PB-R-02 —— 事件用错了端点
修复： 使用与事件相符的路径：
| 事件 | 路径 |
|---|---|
| 玩家账号创建 | /v1/pb/{partner}/registration |
| 首次充值 | /v1/pb/{partner}/first-deposit |
| 之后的充值 | /v1/pb/{partner}/repeat-deposit |
| 收入分成结算 | /v1/pb/{partner}/revenue |
| App 启动（每一次启动） | /v1/pb/{partner}/app-launch |
没有其他路径。App 安装不是启动，也没有对应的 postback 路径——安装通过你的 MMP 回传。从启动路径发出的注册，或从注册路径发出的启动，都会被永久错误归类，与充值走错路径一样。
/revenue 上的负 amount 是合法的——在收入分成下，亏损的周期就是一次负的收入事件。如果你需要专门上报拒付或追回（chargeback / clawback），请与你的客户经理约定表示方式，而不要想当然地认为一条负收入会被这样解读。
把 event 宏设对并没有帮助——它只作交叉核对记录，绝不用于判定类型。只有路径才算数。
PB-R-03 —— 没有可用的身份标识
修复： 发送 click_id（首选）或 user_id。至少有一个必须解析为真实值。
请对照你的日志检查，而不是凭假设：响应是 200，所以你的后台几乎肯定会把这些报告为已送达。
PB-R-04 —— 未替换的宏
修复： 触发一条测试 postback，然后回读存储下来的值。如果 click_id 以字面量 {click_id} 或 {sub1} 到达，说明你后台里的宏名与该平台实际替换的宏名不一致。
在 click_id 和 user_id 以外的字段中，未替换的宏不会导致 postback 被丢弃：该字段会被省略，但字面值会保留下来供诊断——而这正是排查哪个宏名写错时要看的东西。
这是上线时最常见的失败，因为一个在配置界面里看起来没问题的模板，只有在真实转化经过它时才会暴露出来。
PB-R-05 —— 首次与后续充值走同一路径
修复： 你的后台必须知道一笔充值是否是该玩家的首充，并路由到对应的路径。如果做不到，就把所有充值都发到 /repeat-deposit 并告知你的客户经理——少算的首充可以补救；发到注册路径的充值则无法补救。
PB-R-06 —— 时间戳用了秒
修复： ts 和 first_deposit_ts 都是 unix 毫秒。把 10 位数的值乘以 1000。
秒级值会被检测、纠正，并视为契约偏离——事件以纠正后的时间存储，同时触发告警。所以它不会在你的日志里表现为失败，但也不是悄无声息地出错：你的客户经理会收到通知。
另外，超过 30 天的历史事件或超过未来 60 分钟的事件会被记录并标记，绝不会被拒绝。
PB-R-07 —— 金额缺失或符号错误
修复： 在每一条充值和收入 postback 上，把 amount 作为带符号的十进制数发送。结算币种为 USD，且不做任何换算，所以请发送 USD。
在收入分成下，负值是合法且预期之中的：运营方亏损的周期就是一次负的收入事件。
PB-R-08 —— 没有稳定的 event_id
修复： 在你自己的系统中为每笔转化生成一个全局唯一的 ID，并作为 event_id 发送。任何重试都发送完全相同的值。
去重优先级依次为 event_id、txid，最后是查询串的逐字节哈希。哈希兜底并不是安全网：改变参数顺序、新增一个字段，或对某个值重新编码，同一笔转化就会被计为两次。 这一点在 /app-launch 上最要紧：同一玩家会多次启动 App，若没有 event_id 和 ts，两次启动可能生成相同的 URL，被合并成一条。
PB-R-09 —— 重试行为错误
修复：
| 响应 | 含义 | 是否重试 |
|---|---|---|
200 {"status":"ok"} | 已写入持久化存储 | 否 |
200 {"status":"ignored"} | 没有可用的身份标识——请修正负载 | 否，结果会完全相同 |
503 {"status":"unavailable"} | 写入未被确认 | 是 |
403 | 密钥错误或 IP 不被允许 | 否 |
200 确认的是写入已完成，而不只是我们收到了请求。
PB-R-10 —— dry run 没有关掉
修复： 从后台注册的 URL 中移除 dry run 参数。dryrun、dryrun=1 和 dryrun=true 都会被接受，所以请搜索 dryrun，而不是某个确切的字符串。dry run 响应带有响应头 X-Ingest-Mode: dryrun，且不记录任何内容。
PB-R-11 —— 标识与你的其他追踪不一致
修复： 在 Web 追踪器（user_id）、S2S（identity.client_user_id）和 postback（user_id）中，对每个玩家使用同一个标识。同样的字符串、同样的大小写，不要一处带前缀而其他处不带。
这一项出错时每条 postback 都会成功，只是数字是错的。事后修正也不会合并已经拆分开的档案。
PB-R-12 —— 从浏览器触发 postback
修复： 使用你联盟平台的服务端 postback 功能来触发。像素或客户端调用会把 k 密钥放进页面源码，会被广告拦截器拦掉，并且玩家每次刷新都会重复触发。
RevoSurge 还可能把 postback 限制在你的出口 IP 白名单内——请向你的客户经理确认是否已为你开启，因为开启后来自浏览器的调用会以 403 失败。
建议项修复方式
PB-O-01 —— 没有 ctx
修复： 传入你的平台提供的投放上下文宏。click_id 缺失或过期时，归因正是靠它恢复的。
PB-O-02 —— 没有 txid
修复： 把你的交易 ID 作为 txid 发送。它是第二去重键，也是你们财务团队对账时依据的字段。
PB-O-03 —— 分类字段为空
修复： 把 hash_id / hash_name 映射到你的链接或账号标识，把 source_id / source_name 映射到你的流量来源。
请发送真实值，而不是占位符。在这里填一个常量比留空更糟，因为它看起来已经填好了，却会悄悄破坏所有基于它的细分报表。
PB-O-04 —— 没有 country
修复： 如果你的平台提供玩家国家，请发送它。
PB-O-05 —— 没有 event 宏
修复： 把你自己的事件类型宏作为 event 发送。它绝不会改变转化的分类方式——那是端点路径的职责——但端点用错这类问题，正是靠它在扭曲一整个月的报表之前被发现。
PB-O-06 —— 没有首充声明
修复： 当你的系统知道 is_new_customer 和 first_deposit_ts 时，请发送它们。我们读不懂的值会记为空值，而不是 0。
PB-O-07 —— 没有归因份额
修复： 如果你在多个来源之间分摊归因，请在 attribution_share 中声明你的份额。它作为你方的声明被记录——绝不会被换算标度，也不会被乘进 amount。
本页无法检查的两件事
- 你的后台在真实转化发生时确实会触发。 即使平台的 postback 规则已被停用、作用于错误的广告系列，或被一个永远不会满足的条件过滤掉，你粘进浏览器的 URL 依然能通过本页的每一条规则。只有上线测试才能证明它确实会触发。
- 你的总数与我们的一致。 归因窗口、分摊归因模型和结算时点都会合理地改变数字。请按
event_id和txid对账，而不是比较总数。
下一步
所有必需规则都通过后，前往交付与上线。