适用版本:酷盈 / Smartdigimkt SDK ≥ 6.5.91(激励视频)
在开发者后台为激励视频广告位开启服务端激励,并配置回调规则、激励名称 / 数量、回调 URL。
接入 SDK 时在 load 传入 s2s_rewarded_data(见第 4 节)。
回调占位符与签名以本文为准;与聚合 Taku 服务端激励 不完全相同(酷盈使用 {request_id}、{task_type},不使用 {trans_id} 等聚合字段)。
服务端激励(Server-to-Server):用户看完激励视频并达到奖励条件时,由平台请求开发者自己的服务器,由开发者校验并下发奖励。
接入步骤:
user_id 与自定义业务参数(见第 4 节)。说明:
user_id、自定义数据(见第 4 节;Android:SDMAdRequest.extraMap,iOS:SDMBaseAd.extra)。开发者需提供可被 GET 访问的回调地址。平台会对 URL 中的占位符做替换,并附带 {sign}。
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}),签名相关字段须一并配置。
| 参数 | 说明 | 备注 |
|---|---|---|
{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}及对应签名串。
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。
请保证回调接口可被 GET 访问,并返回明确的 HTTP 状态码,便于对账。
回调 URL 可能较长(尤其含
ilrd时),请去掉网关对 GET URL 长度的限制,避免414。
只改 激励视频 的加载代码:在调用激励视频 load 之前(或随同本次 load 的请求参数)传入 s2s_rewarded_data。
不是在 show、也不是在奖励回调里设置。是否开启服务端激励由开发者后台配置,代码里无需判断开关。
调用位置示意:
SDMRewardedVideoAd)s2s_rewarded_data(本节)load → 之后按原有流程 show、收客户端奖励回调| Key | 位置 | 说明 |
|---|---|---|
s2s_rewarded_data |
扩展参数顶层 | 固定保留字;值必须是字典 / Map,不能传 JSON 字符串 |
user_id |
s2s_rewarded_data 内部 |
固定保留字;可选,建议传,用于服务端识别用户 |
写错(改名 / 大小写不一致)时等同于未传。
user_id 以外的键为自定义业务字段。回调中的 extra_data 为整个 s2s_rewarded_data 的 JSON 字符串,同时 user_id 会单独出现在 {user_id} 占位符中。
在激励视频 load 时,把 s2s_rewarded_data 放进本次 SDMAdRequest.extraMap:
// 已有: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 即可。
在激励视频调用 load / loadAdWithExtraDic: 之前,写入广告对象的 extra:
// 已有: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。| 项 | 说明 |
|---|---|
s2s_rewarded_data |
固定 key;值必须是字典 / Map |
user_id |
固定 key;可选。未传则回调中省略 {user_id};传空串 "" 会保留 |
extra_data |
整个 s2s_rewarded_data(含 user_id)的 JSON 字符串 |
| 生效时机 | 以本次激励视频 load 时的值为准;load 之后再改不影响本次广告 |
| 不传 | 可选;不传不影响广告加载与客户端激励回调,回调中同时省略 user_id 与 extra_data |
| 项 | 说明 |
|---|---|
| 普通奖励 | task_type = 2(看完激励视频)。iOS 对应 onAdReward:trackDict: |
| 深度任务奖励 | task_type = 1。iOS 对应 onRewardedSuccess:trackDict: |
| 双奖励 | 同一次展示若先后达成两类奖励,会分别回调两次 |
| 与客户端回调 | 客户端激励回调照常触发;请勿在客户端回调里自行再请求平台服务端激励接口 |
| 未开启时 | 后台未开启服务端激励时,即使传了参数也不会发起服务端回调 |
(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 内;用户已实际达成奖励条件。