激励视频服务端回调

激励视频支持两种发奖方式：

客户端发奖（默认）：未配置回调地址时，由客户端回调通知发奖（onAdReward 等）；
服务端发奖：在控制台为激励视频广告位配置回调地址并开启后，用户完成激励后由 KeyPuff 服务端回调您的服务器验证通过，SDK 才判定激励成功，防刷更可靠。

服务端发奖要求：Android SDK ≥ 5.1.4、iOS SDK ≥ 5.1.5。

配置

在控制台「应用与广告位」中打开对应应用，点击激励视频广告位的“激励回调”进行配置：

配置项	说明
服务端回调开关	开启后走服务端验证
激励名称 / 激励数量	随回调透传给您的服务端
回调地址	必须为公网可访问的 http / https 地址（拒绝内网、回环与保留地址）
Security Key	首次开启时生成，可查看、可重置；重置后旧 Key 立即失效

Security Key 保密

Security Key 只能保存在您的服务端用于验签，不要写进客户端代码或打包进 App。

回调流程

SDK（用户 App 内）：用户完成激励后，SDK 上报激励事件（user_id、extra 等字段）到 KeyPuff 服务端；
KeyPuff 服务端：校验激励请求签名与有效期后，GET 您配置的回调地址，追加上报字段并以服务端值覆盖关键参数，附加 secret 参数；
开发者服务端：校验 secret = md5(adspotid + securityKey + timestamp)；
开发者服务端响应体返回 success；
KeyPuff 通知 SDK 激励验证成功（code = 1），您按业务逻辑发奖。

KeyPuff 发起的回调为 GET 请求：将 SDK 上报的字段追加到您配置的回调地址查询串之后，再由 KeyPuff 服务端写入下列参数（SDK 上报的同名字段不会覆盖它们）。字段包括：

参数	说明
`timestamp`	KeyPuff 服务端发放时间戳（毫秒，参与 secret 计算）
`trans_id`	本次激励的事务 ID（KeyPuff 签名的请求 ID，每次激励唯一）
`reward_name` / `reward_amount`	激励名称 / 数量（控制台配置值；客户端在 SDK 代码中设置的数量不会传给您）
`placement_id`	KeyPuff 广告位 id（adspotid）
`user_id`	客户端设置的 userId（SDK 透传）
`extra`	客户端设置的透传参数（SDK 透传）
`adn_channel_id` / `adn_adspot_id`	胜出渠道的渠道 id 与广告位 id（SDK 透传）
`is_cached` / `cached_reqid`	是否缓存广告及其关联请求 id（SDK 透传）
`secret`	`md5(adspotid + securityKey + timestamp)` 的小写十六进制

示例（URL 已简化）：

GET https://dev.example.com/reward?timestamp=1789000000000&user_id=42
    &extra=%7B%22k%22%3A%22v%22%7D&reward_name=%E9%87%91%E5%B8%81&reward_amount=1
    &trans_id=...&placement_id=10000004&adn_channel_id=3&adn_adspot_id=...
    &is_cached=0&cached_reqid=&secret=8f3a...c2

验证回调配置：发送测试回调

配置保存后，可以在控制台「应用与广告位」→ 激励视频广告位 →「激励回调」弹窗中点击 发送测试回调，向已配置的回调地址发起一次验证请求，无需真实投放广告。

测试回调与真实回调使用完全相同的签名与参数规则（secret = md5(adspotid + securityKey + timestamp)），但通过以下固定标记识别：

参数	测试回调的值	说明
`trans_id`	`creative_test_` + 16 位随机 hex	真实回调的 `trans_id` 为签名请求 ID，不会有该前缀
`user_id`	`creative_test_user`	固定值
`extra`	`{"creative_test":true}`	JSON 标记

测试回调不发奖

测试回调仅供验证网络可达与验签逻辑。请在您的服务端按上述标记识别测试请求并跳过发奖（仍按正常流程校验 secret 并响应 success，即可在控制台看到「测试回调成功」）。

限制与说明：

每广告位每小时最多发送 5 次，超限返回限流提示；
测试回调同样要求回调地址公网可达（内网、回环与保留地址会被拒绝），超时 / 非 2xx / 响应非 success 会直接显示失败原因；
每次发送都会记录操作日志（审计），测试回调不会出现在下方「回调记录」中（记录只统计真实激励上报）。

回调记录查询

控制台「激励回调」弹窗下方展示该广告位最近的服务端回调记录，包括：

时间：KeyPuff 服务端接收 SDK 激励上报的时间；
trans_id：该次激励的事务 ID，可据此在您的服务端日志中定位对应请求；
结果：成功，或失败类别——回调超时 / 网络错误 / 响应非 2xx / 响应不是 success / 回调地址为内网被拒 / 回调地址非法。

默认显示最近 24 小时（可选最近 3 天 / 7 天），最多最近 50 条，原始事件保留 90 天。SDK 侧判定为「请求无效或重复」（code -1）的上报也在记录中。若记录持续显示失败，请按类别排查后使用「发送测试回调」验证。

验签实现

在您的服务端按相同公式计算并比对 secret（md5 小写十六进制，输入为三段字符串直接拼接）。Java 示例：

java

String secret = md5Hex(placementId + securityKey + timestamp); // securityKey 只存服务端
if (!secret.equals(request.getParameter("secret"))) {
    // 验签失败，拒绝发奖
    return;
}
respond("success");

注意事项：

响应体必须为文本 success（忽略首尾空白，例如 success\n 可接受）；响应其他内容、非 2xx 或超时（3000 ms）均视为验证失败；
adspotid 使用 KeyPuff 分配的广告位 id（即回调中的 placement_id）；
回调地址需公网可达；KeyPuff 服务端会校验解析出的目标 IP，内网、保留地址与云厂商元数据段会被拒绝；
timestamp 为 KeyPuff 服务端时间，重放与超期请求已在 KeyPuff 侧拦截；同一激励 KeyPuff 保证最多一次成功回调。仍建议按 trans_id 做幂等兜底：若您的服务端响应失败，用户重试会再次触发回调（trans_id 不变）。

SDK 侧结果码

服务端验证结果通过 SDK 回调返回（SDK 以 code == 1 判定成功）：

code	含义	开发者处理
1	验证成功	正常发奖
-1	请求非法 / 已过期；或重复提交（msg = `Duplicate reward`，KeyPuff 不再回调）。未配置回调地址不属于错误：此时走客户端发奖，返回 code 1 直接成功	走客户端发奖逻辑
-2	激励信息缺失	检查 rewardVideoModel（userId 等）设置
-3	回调失败（网络异常、验签未通过、响应非 success）	不发奖；排查服务端日志与回调地址可达性；用户重试会再次回调，请按 `trans_id` 幂等

对应客户端回调：iOS onRewardVideoAdDidServerRewardFail:、Android onRewardServerInf、鸿蒙 onAdServerRewardFail。

常见问题

回调一直收不到：确认回调地址公网可达、未配置在需要登录态的路径上；先在控制台「发送测试回调」验证网络与验签，再看「回调记录」中的失败类别；
SDK 提示 code -3：检查服务端是否返回了文本 success，以及 Security Key 是否在重置后未同步更新；
控制台如何核对：控制台「应用与广告位」的激励回调配置可查看回调地址与 Security Key 状态，并可发送测试回调、查看最近回调记录（见上文）。

激励视频服务端回调 ​

配置 ​

回调流程 ​

验证回调配置：发送测试回调 ​

回调记录查询 ​

验签实现 ​

SDK 侧结果码 ​

常见问题 ​