DeepAdx 激励回调服务端接入文档
本文档面向 APP 服务端。
APP 服务端无需区分不同广告来源,只需要对接 DeepAdx 统一回调协议。
1. 回调触发时机
当满足以下条件时,DeepAdx 会回调 APP 服务端:
- DeepAdx 已收到激励结果
- DeepAdx 已完成激励结果校验
- 该广告位已配置 APP 服务端回调地址与回调密钥
说明:
- DeepAdx 对 APP 服务端的回调是
GET请求 - 目前默认按单次回调处理,APP 服务端需要自行做好幂等
2. APP 服务端需要提供的信息
这两个字段是在 创建广告位时填写 的:
callback_urlAPP 服务端用于接收 DeepAdx 激励通知的回调地址callback_api_keyAPP 服务端与 DeepAdx 约定的接口密钥,用于签名校验
也就是说,APP 在 DeepAdx 平台创建激励广告位时,需要同时配置:
- 一个回调地址:
callback_url - 一个接口密钥:
callback_api_key
建议按“一个广告位一套回调配置”的方式管理,便于隔离、排查和后续密钥轮换。
建议:
callback_url使用 HTTPScallback_api_key长度至少 16 位以上- 不同 APP / 不同广告位建议使用独立密钥,便于隔离和轮换
3. 回调方式
- 请求方法:
GET - 请求超时:DeepAdx 当前请求超时为
10s - 查询参数:通过 URL Query 传递
示例:
GET https://api.xxx.com/ad/reward/callback?user_id=10001&trans_id=csj_792739423&reward_name=%E9%87%91%E5%B8%81&reward_amount=100&extra=task_20260513_001&sign=abcdef1234567890&app_id=deepadx_app_001&placement_id=reward_0014. 回调参数说明
当前 DeepAdx 回调 APP 服务端时,会带以下参数:
| 参数名 | 是否必有 | 说明 |
|---|---|---|
user_id | 建议有 | 媒体侧传入的用户 ID |
trans_id | 是 | DeepAdx 生成的交易号,格式为 平台前缀_媒体原始交易号 |
reward_name | 可能为空 | 奖励名称,例如金币、积分 |
reward_amount | 是 | 奖励数量,整数 |
extra | 可能为空 | 业务扩展参数 |
sign | 是 | DeepAdx 生成的签名 |
app_id | 可能有 | DeepAdx 应用 ID |
placement_id | 可能有 | DeepAdx 广告位 ID |
4.1 trans_id 规则
DeepAdx 回调 APP 服务端时,不直接透传原始单号,而是统一加上平台前缀:
{platform}_{media_trans_id}示例:
csj_792739423ylh_abc123456gg_987654321
这样做的目的是:
- 避免不同来源的交易号发生冲突
- 方便 APP 服务端按平台排查问题
- 方便做统一幂等键设计
APP 服务端建议直接使用 trans_id 作为业务幂等主键之一。
4.2 extra 回传规则
extra 是客户端传入的业务扩展参数。
APP 服务端接入时,可以直接把它理解成 业务透传字段,DeepAdx 回调 APP 服务端时会回传该业务 extra,你可以用它承载例如:
- 订单号
- 任务 ID
- 活动 ID
- 用户任务流水号
建议:
extra尽量保持简洁、稳定、可追踪- 推荐直接放业务主键或业务流水号
- 如果未传
extra,回调中该字段可能为空
5. 签名规则
5.1 签名算法
DeepAdx 回调 APP 服务端时,签名算法固定为:
sha256(callback_api_key + ":" + trans_id)输出格式为:
- 小写十六进制字符串
也就是说,签名使用的是:
- 你在 DeepAdx 配置的
callback_api_key - DeepAdx 回调给你的
trans_id
5.2 签名示例
假设:
callback_api_key = my_secret_key_123
trans_id = csj_792739423那么待签名原文为:
my_secret_key_123:csj_792739423再对这段字符串做 SHA-256,最后转成小写 hex,即得到 sign。
5.3 APP 服务端验签示例
下面给一个 Java 示例:
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
public class DeepAdxRewardSignUtil {
/**
* 使用 DeepAdx 约定的签名规则生成签名。
*
* @param callbackApiKey APP 服务端与 DeepAdx 约定的密钥
* @param transId DeepAdx 回调中的 trans_id
* @return 小写十六进制 sha256 签名
*/
public static String sign(String callbackApiKey, String transId) throws Exception {
// 按协议拼接原文:key:trans_id
String raw = callbackApiKey.trim() + ":" + transId.trim();
// 计算 SHA-256 摘要
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] bytes = digest.digest(raw.getBytes(StandardCharsets.UTF_8));
// 转成小写十六进制
StringBuilder sb = new StringBuilder();
for (byte b : bytes) {
sb.append(String.format("%02x", b));
}
return sb.toString();
}
/**
* 验签入口。
*
* @param callbackApiKey 配置给 DeepAdx 的回调密钥
* @param transId DeepAdx 回调中的 trans_id
* @param sign DeepAdx 回调中的 sign
* @return true 表示验签通过
*/
public static boolean verify(String callbackApiKey, String transId, String sign) throws Exception {
// 重新计算本地签名,并与回调中的 sign 做忽略大小写比较
return sign(callbackApiKey, transId).equalsIgnoreCase(sign);
}
}6. APP 服务端成功响应规范
DeepAdx 判断 APP 服务端回调是否成功,规则非常明确:
- HTTP 状态码必须是
2xx - 响应体必须能解析成 JSON
- JSON 中必须包含:
{
"isValid": true
}注意:
isValid必须是布尔值true- 不是字符串
"true" - 不是数字
1 - 如果缺少该字段,或字段值不是
true,DeepAdx 都会视为失败
推荐成功响应:
{
"isValid": true
}推荐失败响应:
{
"isValid": false,
"message": "sign verify failed"
}7. APP 服务端处理建议
建议 APP 服务端按下面顺序处理:
- 接收 DeepAdx 的 GET 回调
- 读取全部 Query 参数
- 使用本地
callback_api_key对trans_id做验签 - 验签通过后,按
trans_id做幂等判断 - 幂等未命中则执行发奖逻辑
- 发奖成功后返回:
{
"isValid": true
}7.1 幂等建议
由于回调链路里存在网络抖动、重复通知、人工补发等可能性,APP 服务端必须做幂等。
推荐使用以下组合作为幂等依据:
trans_id
如果你的业务更严格,也可以联合以下字段辅助校验:
user_idreward_namereward_amountextra
但最核心的唯一标识仍建议使用 trans_id。
7.2 发奖建议
建议 APP 服务端不要只根据客户端本地回调发奖,而是以 DeepAdx 服务端回调 为准做最终发奖。
典型做法:
- 客户端展示“奖励校验中”
- APP 服务端收到 DeepAdx 回调
- APP 服务端验签成功
- APP 服务端完成幂等判断与发奖
- 客户端轮询或刷新奖励状态
8. 完整回调示例
8.1 DeepAdx 发起的回调
GET /ad/reward/callback?user_id=10001&trans_id=csj_792739423&reward_name=%E9%87%91%E5%B8%81&reward_amount=100&extra=task_20260513_001&sign=4d2b7d0f2c8a7e7c3b3a2b0a2e1f1d7d1a2b3c4d5e6f7081920a0b0c0d0e0f10&app_id=deepadx_app_001&placement_id=reward_0018.2 APP 服务端成功响应
{
"isValid": true
}8.3 APP 服务端失败响应
{
"isValid": false,
"message": "duplicate trans_id"
}9. 常见问题
9.1 为什么我收到了回调,但 DeepAdx 仍然认为失败?
通常有以下几种原因:
- 你的接口返回了非
2xx - 你的响应体不是合法 JSON
- 你的 JSON 里没有
isValid - 你的
isValid不是布尔值true
9.2 extra 应该怎么用?
把 extra 当作业务透传字段使用即可,推荐放:
- 订单号
- 任务 ID
- 活动 ID
- 用户任务流水号
APP 服务端按自己的业务字段解析和使用 extra 即可,无需关心 SDK 内部处理细节。
9.3 为什么 trans_id 比原始单号多了平台前缀?
因为 DeepAdx 对 APP 服务端统一输出的格式是:
{platform}_{media_trans_id}这样可以避免不同平台的交易号冲突。
9.4 DeepAdx 会重试吗?
当前按单次回调处理,文档约定里不保证自动重试。
因此建议:
- APP 服务端保证接口稳定可用
- 接口响应尽量快速
- 发奖逻辑与回调接收逻辑解耦
10. 推荐落地方案
如果你是第一次接 DeepAdx 服务端回调,推荐按下面顺序落地:
- 先提供一个测试回调地址给 DeepAdx
- 先只做验签和日志记录,不立即发奖
- 确认
trans_id / user_id / extra / sign都符合预期 - 再补充正式幂等逻辑
- 最后再接入真实发奖逻辑
一句话总结:
APP 服务端只需要做三件事:验签、幂等、发奖,然后返回 {"isValid": true}。
