Skip to content

DeepAdx 激励回调服务端接入文档 ​

本文档面向 APP 服务端。

APP 服务端无需区分不同广告来源,只需要对接 DeepAdx 统一回调协议。

1. 回调触发时机 ​

当满足以下条件时,DeepAdx 会回调 APP 服务端:

  1. DeepAdx 已收到激励结果
  2. DeepAdx 已完成激励结果校验
  3. 该广告位已配置 APP 服务端回调地址与回调密钥

说明:

  • DeepAdx 对 APP 服务端的回调是 GET 请求
  • 目前默认按单次回调处理,APP 服务端需要自行做好幂等

2. APP 服务端需要提供的信息 ​

这两个字段是在 创建广告位时填写 的:

  1. callback_url APP 服务端用于接收 DeepAdx 激励通知的回调地址

  2. callback_api_key APP 服务端与 DeepAdx 约定的接口密钥,用于签名校验

也就是说,APP 在 DeepAdx 平台创建激励广告位时,需要同时配置:

  • 一个回调地址:callback_url
  • 一个接口密钥:callback_api_key

建议按“一个广告位一套回调配置”的方式管理,便于隔离、排查和后续密钥轮换。

建议:

  • callback_url 使用 HTTPS
  • callback_api_key 长度至少 16 位以上
  • 不同 APP / 不同广告位建议使用独立密钥,便于隔离和轮换

3. 回调方式 ​

  • 请求方法:GET
  • 请求超时:DeepAdx 当前请求超时为 10s
  • 查询参数:通过 URL Query 传递

示例:

text
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_001

4. 回调参数说明 ​

当前 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 服务端时,不直接透传原始单号,而是统一加上平台前缀:

text
{platform}_{media_trans_id}

示例:

  • csj_792739423
  • ylh_abc123456
  • gg_987654321

这样做的目的是:

  • 避免不同来源的交易号发生冲突
  • 方便 APP 服务端按平台排查问题
  • 方便做统一幂等键设计

APP 服务端建议直接使用 trans_id 作为业务幂等主键之一。

4.2 extra 回传规则 ​

extra 是客户端传入的业务扩展参数。

APP 服务端接入时,可以直接把它理解成 业务透传字段,DeepAdx 回调 APP 服务端时会回传该业务 extra,你可以用它承载例如:

  • 订单号
  • 任务 ID
  • 活动 ID
  • 用户任务流水号

建议:

  • extra 尽量保持简洁、稳定、可追踪
  • 推荐直接放业务主键或业务流水号
  • 如果未传 extra,回调中该字段可能为空

5. 签名规则 ​

5.1 签名算法 ​

DeepAdx 回调 APP 服务端时,签名算法固定为:

text
sha256(callback_api_key + ":" + trans_id)

输出格式为:

  • 小写十六进制字符串

也就是说,签名使用的是:

  1. 你在 DeepAdx 配置的 callback_api_key
  2. DeepAdx 回调给你的 trans_id

5.2 签名示例 ​

假设:

text
callback_api_key = my_secret_key_123
trans_id = csj_792739423

那么待签名原文为:

text
my_secret_key_123:csj_792739423

再对这段字符串做 SHA-256,最后转成小写 hex,即得到 sign。

5.3 APP 服务端验签示例 ​

下面给一个 Java 示例:

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 服务端回调是否成功,规则非常明确:

  1. HTTP 状态码必须是 2xx
  2. 响应体必须能解析成 JSON
  3. JSON 中必须包含:
json
{
  "isValid": true
}

注意:

  • isValid 必须是布尔值 true
  • 不是字符串 "true"
  • 不是数字 1
  • 如果缺少该字段,或字段值不是 true,DeepAdx 都会视为失败

推荐成功响应:

json
{
  "isValid": true
}

推荐失败响应:

json
{
  "isValid": false,
  "message": "sign verify failed"
}

7. APP 服务端处理建议 ​

建议 APP 服务端按下面顺序处理:

  1. 接收 DeepAdx 的 GET 回调
  2. 读取全部 Query 参数
  3. 使用本地 callback_api_key 对 trans_id 做验签
  4. 验签通过后,按 trans_id 做幂等判断
  5. 幂等未命中则执行发奖逻辑
  6. 发奖成功后返回:
json
{
  "isValid": true
}

7.1 幂等建议 ​

由于回调链路里存在网络抖动、重复通知、人工补发等可能性,APP 服务端必须做幂等。

推荐使用以下组合作为幂等依据:

  • trans_id

如果你的业务更严格,也可以联合以下字段辅助校验:

  • user_id
  • reward_name
  • reward_amount
  • extra

但最核心的唯一标识仍建议使用 trans_id。

7.2 发奖建议 ​

建议 APP 服务端不要只根据客户端本地回调发奖,而是以 DeepAdx 服务端回调 为准做最终发奖。

典型做法:

  1. 客户端展示“奖励校验中”
  2. APP 服务端收到 DeepAdx 回调
  3. APP 服务端验签成功
  4. APP 服务端完成幂等判断与发奖
  5. 客户端轮询或刷新奖励状态

8. 完整回调示例 ​

8.1 DeepAdx 发起的回调 ​

text
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_001

8.2 APP 服务端成功响应 ​

json
{
  "isValid": true
}

8.3 APP 服务端失败响应 ​

json
{
  "isValid": false,
  "message": "duplicate trans_id"
}

9. 常见问题 ​

9.1 为什么我收到了回调,但 DeepAdx 仍然认为失败? ​

通常有以下几种原因:

  1. 你的接口返回了非 2xx
  2. 你的响应体不是合法 JSON
  3. 你的 JSON 里没有 isValid
  4. 你的 isValid 不是布尔值 true

9.2 extra 应该怎么用? ​

把 extra 当作业务透传字段使用即可,推荐放:

  • 订单号
  • 任务 ID
  • 活动 ID
  • 用户任务流水号

APP 服务端按自己的业务字段解析和使用 extra 即可,无需关心 SDK 内部处理细节。

9.3 为什么 trans_id 比原始单号多了平台前缀? ​

因为 DeepAdx 对 APP 服务端统一输出的格式是:

text
{platform}_{media_trans_id}

这样可以避免不同平台的交易号冲突。

9.4 DeepAdx 会重试吗? ​

当前按单次回调处理,文档约定里不保证自动重试。

因此建议:

  • APP 服务端保证接口稳定可用
  • 接口响应尽量快速
  • 发奖逻辑与回调接收逻辑解耦

10. 推荐落地方案 ​

如果你是第一次接 DeepAdx 服务端回调,推荐按下面顺序落地:

  1. 先提供一个测试回调地址给 DeepAdx
  2. 先只做验签和日志记录,不立即发奖
  3. 确认 trans_id / user_id / extra / sign 都符合预期
  4. 再补充正式幂等逻辑
  5. 最后再接入真实发奖逻辑

一句话总结:

APP 服务端只需要做三件事:验签、幂等、发奖,然后返回 {"isValid": true}。

DeepAdx SDK 官方文档