菜单

酷盈服务端激励

服务端激励 Server to Server Reward Callbacks

适用版本:酷盈 / Smartdigimkt SDK ≥ 6.5.91(激励视频)

在开发者后台为激励视频广告位开启服务端激励,并配置回调规则、激励名称 / 数量、回调 URL。
接入 SDK 时在 load 传入 s2s_rewarded_data(见第 4 节)。
回调占位符与签名以本文为准;与聚合 Taku 服务端激励 不完全相同(酷盈使用 {request_id}、{task_type},不使用 {trans_id} 等聚合字段)。

1. 服务端激励介绍

服务端激励(Server-to-Server):用户看完激励视频并达到奖励条件时,由平台请求开发者自己的服务器,由开发者校验并下发奖励。

接入步骤:

  1. 在开发者后台打开激励视频广告位的服务端激励,并配置回调 URL。
  2. 在酷盈 SDK 加载广告时传入 user_id 与自定义业务参数(见第 4 节)。
  3. 用户达成奖励后,平台以 GET 请求开发者配置的回调 URL(占位符替换 + 签名)。

说明:

  • 适用于 酷盈 SDK 直接接入 的激励视频。若通过聚合 SDK 接入,请按聚合侧的服务端激励文档配置,无需在酷盈 SDK 中重复传参。
  • 是否发奖以开发者服务器收到回调并完成校验为准。
  • 客户端激励回调仍会正常触发;与是否已完成服务端回调相互独立。

2. 使用流程

  1. 在开发者后台的激励视频广告位开启服务端激励,填写回调规则、激励名称、激励数量、回调 URL。
  2. 在激励视频 load 之前 / 随 load 请求 传入 user_id、自定义数据(见第 4 节;Android:SDMAdRequest.extraMap,iOS:SDMBaseAd.extra)。
  3. 用户看完激励视频(或完成深度任务)后,平台按回调 URL 通知开发者服务器,由开发者校验并下发奖励。

3. 开发者服务端接入

开发者需提供可被 GET 访问的回调地址。平台会对 URL 中的占位符做替换,并附带 {sign}。

3.1 回调示例

text 复制代码
https://www.example.com/onrewardedverify?user_id={user_id}&extra_data={extra_data}&request_id={request_id}&reward_name={reward_name}&task_type={task_type}&reward_amount={reward_amount}&placement_id={placement_id}&package_name={package_name}&platform={platform}&ilrd={ilrd}&sign={sign}

不必配置全部占位符,按需选择。若使用签名(配置了 sign={sign}),签名相关字段须一并配置。

3.2 占位符说明

参数 说明 备注
{user_id} 用户 ID 由开发者通过 SDK 设置(见第 4 节)
{extra_data} 业务自定义参数 由开发者通过 SDK 设置
{request_id} 本次请求唯一 ID 建议发奖前按 request_id + task_type 防重
{reward_name} 激励名称 取自开发者后台(支持广告位或广告场景)
{task_type} 激励类型 2:普通任务(看视频奖励);1:深度任务(应用调起、安装完成等)
{reward_amount} 激励数量 取自开发者后台(支持广告位或广告场景)
{placement_id} 广告位 ID —
{package_name} 应用包名或 Bundle ID —
{platform} 系统平台 1:Android,2:iOS
{ilrd} 本次展示价格(加密) 需换算为开发者后台货币单位;密钥为后台配置的广告位 sec key
{sign} 签名 见下方签名规则

请勿直接套用聚合文档中的 {trans_id}、{network_firm_id}、{adsource_id}、{scenario_id} 及对应签名串。

3.3 签名规则

text 复制代码
sign = MD5("request_id="+request_id+"&placement_id="+placement_id+"&task_type="+task_type+"&reward_amount="+reward_amount+"&reward_name="+reward_name+"&sec_key="+sec_key)

sec_key 取自开发者后台该广告位的服务端激励配置。

建议去重口径:request_id + task_type + app_id + placement_id。

3.4 回调响应

请保证回调接口可被 GET 访问,并返回明确的 HTTP 状态码,便于对账。

回调 URL 可能较长(尤其含 ilrd 时),请去掉网关对 GET URL 长度的限制,避免 414。

4. SDK 接入

只改 激励视频 的加载代码:在调用激励视频 load 之前(或随同本次 load 的请求参数)传入 s2s_rewarded_data。
不是在 show、也不是在奖励回调里设置。是否开启服务端激励由开发者后台配置,代码里无需判断开关。

调用位置示意:

  1. 创建激励视频广告对象(如 SDMRewardedVideoAd)
  2. 设置 s2s_rewarded_data(本节)
  3. 调用 load → 之后按原有流程 show、收客户端奖励回调

4.1 固定 key(不可改名)

Key 位置 说明
s2s_rewarded_data 扩展参数顶层 固定保留字;值必须是字典 / Map,不能传 JSON 字符串
user_id s2s_rewarded_data 内部 固定保留字;可选,建议传,用于服务端识别用户

写错(改名 / 大小写不一致)时等同于未传。
user_id 以外的键为自定义业务字段。回调中的 extra_data 为整个 s2s_rewarded_data 的 JSON 字符串,同时 user_id 会单独出现在 {user_id} 占位符中。

4.2 Android

在激励视频 load 时,把 s2s_rewarded_data 放进本次 SDMAdRequest.extraMap:

java 复制代码
// 已有:SDMRewardedVideoAd rewardedVideoAd = new SDMRewardedVideoAd(context, placementId);

Map<String, Object> rewardedData = new HashMap<>();
rewardedData.put("user_id", "your_user_id");       // 固定 key;可选,建议传
rewardedData.put("custom_key", "custom_value");    // 自定义业务字段

Map<String, Object> extraMap = new HashMap<>();
extraMap.put("s2s_rewarded_data", rewardedData);   // 固定 key;值为 Map,不是 JSON 字符串

SDMAdRequest request = new SDMAdRequest.Builder()
        .setExtraMap(extraMap)
        .build();
rewardedVideoAd.load(request);   // 用带 extraMap 的 load,不要再用无参 load()

若本次加载还要传服务端竞价 s2s_bid_adm,与 s2s_rewarded_data 同级放进同一个 extraMap 即可。

4.3 iOS

在激励视频调用 load / loadAdWithExtraDic: 之前,写入广告对象的 extra:

objc 复制代码
// 已有:SDMRewardedVideoAd *rewardedVideoAd = [[SDMRewardedVideoAd alloc] initAdWithPlacementId:placementId];

rewardedVideoAd.extra = @{
    @"s2s_rewarded_data": @{
        @"user_id": @"your_user_id",   // 固定 key;可选,建议传
        @"custom_key": @"custom_value" // 自定义业务字段
    }
};
[rewardedVideoAd load];   // 先设 extra,再 load

说明:

  • 必须写在 SDMBaseAd.extra;loadAdWithExtraDic: 的入参不能用来传 s2s_rewarded_data。
  • 同一广告对象多次 load 时,每次加载前都要重新设置 extra。

4.4 参数规则

项 说明
s2s_rewarded_data 固定 key;值必须是字典 / Map
user_id 固定 key;可选。未传则回调中省略 {user_id};传空串 "" 会保留
extra_data 整个 s2s_rewarded_data(含 user_id)的 JSON 字符串
生效时机 以本次激励视频 load 时的值为准;load 之后再改不影响本次广告
不传 可选;不传不影响广告加载与客户端激励回调,回调中同时省略 user_id 与 extra_data

5. 奖励类型与回调

项 说明
普通奖励 task_type = 2(看完激励视频)。iOS 对应 onAdReward:trackDict:
深度任务奖励 task_type = 1。iOS 对应 onRewardedSuccess:trackDict:
双奖励 同一次展示若先后达成两类奖励,会分别回调两次
与客户端回调 客户端激励回调照常触发;请勿在客户端回调里自行再请求平台服务端激励接口
未开启时 后台未开启服务端激励时,即使传了参数也不会发起服务端回调

6. 常见问题

(1) 和聚合后台的服务端激励有什么区别?

配置入口仍在开发者后台。占位符与签名请以本文为准,不要直接套用聚合文档中的 {trans_id} 等字段。

(2) 走聚合接入还要不要在酷盈 SDK 里传 s2s_rewarded_data?

不必。聚合场景请按聚合 SDK 文档传入用户参数;本文第 4 节适用于酷盈 SDK 直接接入。

(3) 只接客户端激励回调够不够?

若需要由己方服务器校验并发奖,请同时接入服务端激励。发奖前建议按 request_id + task_type 防重。

(4) extra_data 里能放什么?

s2s_rewarded_data 中的字段都会进入 extra_data。请避免过长内容或敏感明文。

(5) 传了参数为什么收不到回调?

请确认:后台已开启服务端激励且回调 URL 可达;s2s_rewarded_data 在 load 前已传入且为字典;user_id 写在 s2s_rewarded_data 内;用户已实际达成奖励条件。

上一个
【接口文档】酷盈openapi
最近修改: 2026-11-19Powered by