服务端激励回调

一、功能概述

Carty 开发者平台提供 服务端激励回调（S2S Postback） 功能，旨在增强激励视频广告奖励发放的安全性。

通过该功能，奖励的发放逻辑从单纯的“客户端回调”升级为“服务端校验”。由 Carty 服务端直接向开发者服务器推送发放通知，有效杜绝通过篡改客户端数据进行刷奖的作弊行为，确保激励体系的公平性与业务数据的准确性。

二、使用流程

2.1 开启服务器激励回调

• 开发者需要在 Carty 后台的激励视频广告位上，开启 服务器激励回调, ，并配置合法的接收地址

• 激励回调地址示例：https://www.dev.com/reward/callback

2.2 传入参数

• 用户开始观看激励视频，开发者需传入用户唯一标识（User ID）及自定义业务参数（Extra）。

2.3 服务端回调

• 用户完成激励视频观看后，Carty 服务端将通过 HTTP GET 请求通知开发者服务器。

2.4 服务端回调

• 开发者服务器接收请求，验证签名（Sign）及交易唯一性（Trans ID），确认无误后执行业务层奖励发放，并按约定格式返回响应。

三 回调协议说明

3.1 请求定义

• 请求方式：HTTP GET

• 字符编码：UTF-8

3.2 字段说明：

字段属性	类型	含义	描述
user_id	String	用户 ID	开发者通过客户端 SDK 传入的业务用户 ID
trans_id	String	唯一交易 ID	Carty SDK 生成的单次观看唯一标识
rewarded_name	String	奖励名称	后台配置的奖励名称
rewarded_value	Int	奖励数量	后台配置的奖励数值
placement_uid	String	广告位 ID	Carty 平台分配的广告位唯一标识
sign	String	安全签名	用于验证请求合法性
extra	String	自定义参数	开发者调用 SDK 时传入的透传字段（(需要 URL Encoding 处理)）

• 请求示例

https://www.dev.com/reward/callback?extra=%7B%22name%22%3A%22user1%22%7D&placement_uid=p201156097019213&rewarded_name=play&rewarded_value=10&sign=0861c6e4e4a83c15a5bcbb028bb1f0a369acf9257156226f12da4315a1579831&trans_id=cf9257156226&user_id=a5bcbb0

3.3 Sign 生成方式及校验

• 开发者收到 Carty 服务端奖励回调后，可以通过 sign 字段校验。

• 生成规则：将 security_key 和 trans_id 使用冒号 :，进行 SHA-256 哈希运算。

• 公式：sign = sha256("security_key:trans_id")。

• 获取途径：security_key 可在 Carty 开发者后台广告位详情页获取。

• sign 示例：

security_key: E5F9F080B1F534C8992C6D81EBBD3E89
trans_id: f2ee29c410b86bf6b

计算结果 (Sign): e9957ec57285c4e3736da2c5ed09ff328883184c12b5ac4a53a63758b4fdfb6c

3.4 回调响应说明

• 开发者收到奖励回调并验证通过后，需要响应约定参数，用于 Carty 服务端确认是否请求正常。

字段属性	类型	含义	描述
is_verify	Boolean	校验结果	开发者服务端判定结果
code	Int	状态码	0 为成功，非 0 为业务错误码
msg	String	错误描述	描述处理结果或失败原因

• 响应示例

{
    "is_verify": true,
    "code": 0,
    "msg": "success"
}

3.4 重试机制

• 触发条件：响应非 HTTP 200、响应超时（2秒）。
• 重试频率：Carty 服务端将发起最多 3 次 重试，以提高回调到达率。

四 客户端 SDK 集成

开发者需在加载或展示激励视频广告前，通过 SDK 接口配置回调上下文。

4.1 Android 实现

• Java

// 在加载激励广告时设置 userId
CTGlobalSettings.getInstance().setExternalUid("your_uid");

// 在加载激励广告时设置 extraParams
Map<String, Serializable> extraParams = new HashMap<>();
extraParams.put("key", "value");
CTAdRequest adRequest = new CTAdRequest.Builder()
        .setPlacementId("your_placement_id")
        .setExtraParams(extraParams)
        .build();
CTReward ctReward = new CTReward(adRequest);
ctReward.setRewardAdListener(listener);
ctReward.loadAd();

• Kotlin

// 在加载激励广告时设置 userId
CTGlobalSettings.getInstance().externalUid = "your_uid"

// 在加载激励广告时设置 extraParams
val extraParams = hashMapOf<String, Serializable>()
extraParams["key"] = "value"
val adRequest = CTAdRequest.Builder()
    .setPlacementId(placementId)
    .setExtraParams(extraParams)
    .build()
ctReward = CTReward(adRequest)
ctReward?.apply {
    setRewardAdListener(listener)
    loadAd()
}

4.2 iOS 实现

• Objective-C

//在展示激励视频之前设置

//设置 user_id
[CartyADSDK sharedInstance].userid = @"your_user_id";

//设置 extra (CTRewardedVideoAd API)
self.rewardedVideoAd.customRewardString = @"your_reward_string";

[self.rewardedVideo showAd:self];

• Swift

//在展示激励视频之前设置

//设置 user_id
CartyADSDK.sharedInstance().userid = "your_user_id"

//设置 extra (CTRewardedVideoAd API)
rewardedVideoAd.customRewardString = "your_reward_string"

rewardedVideoAd.show(self)