服务端激励

1. 服务端激励介绍

服务端激励（Server-to-Server）：允许开发者自己判断是否下发奖励给观看激励视频的用户。当用户看完激励视频时，将通知开发者的服务器，由开发者自己进行奖励的下发

• Taku SDK < v5.7.56 开发者需要使用第三方广告平台服务端激励
• Taku SDK >= v5.7.56 开发者可以使用Taku服务端激励

注意：为了保障服务端激励的准确性，针对第三方广告平台建议开发者优先使用第三方广告平台的服务端激励回调。针对Taku Adx、直投、交叉推广，开发者可以直接使用Taku的服务端激励回调。您可以根据 Network Firm ID来判断是否只接受Taku服务端激励回调：

1. Taku Adx的Network Firm ID=66

2. Taku 直投广告的Network Firm ID=67

3. Taku 交叉推广的Network Firm ID=35

2. 第三方广告平台服务端激励的使用流程

1. 开发者需要到第三方广告平台的后台设置开发者自己服务器的回调URL地址
2. 开发者在代码中通过Taku SDK的API传入UserID（用户唯一ID）、UserCustomData（用户自定义数据). 这些参数最终将通过回调URL通知开发者
3. 当用户看完激励视频时，广告平台将通过设置的回调URL地址通知开发者，由开发者自行判断并下发奖励

支持服务端激励的广告平台如下：（可点击跳转到广告平台关于服务端激励的文档说明，不能跳转的请直接登录广告平台后台进行回调URL的设置）

2.1 Android

2.2 iOS

3. Taku服务端激励的使用说明

• Taku SDK >= v5.7.56可以使用Taku服务激励回调
• Taku SDK >= v5.7.78及以上版本支持在Taku服务激励回调中返回展示级别的数据（开发者可以在回调URL中添加{ilrd}参数获取相应数据)

3.1 服务端激励使用流程

1. 开发者需要在Taku后台的激励视频广告位上打开服务端激励，并设置回调URL地址
2. 开发者需要在代码中通过Taku SDK的API传入UserID（用户唯一ID）、UserCustomData（用户自定义数据). 这些参数最终将通过回调URL通知开发者
3. 当用户看完激励视频时，Taku平台将通过设置的回调URL地址通知开发者，由开发者自行判断并下发奖励

3.2 开发者的服务端激励接入指南

1. 开发者需要Taku后台的激励视频广告位打开服务端激励，并设置开发者服务端激励的回调URL，示例如下：

1. 开发者的回调URL示例如下：

https://www.takuad.com/onrewardedverify?user_id={user_id}&trans_id={trans_id}&reward_amount={reward_amount}&reward_name={reward_name}&placement_id={placement_id}&extra_data={extra_data}&network_firm_id={network_firm_id}&adsource_id={adsource_id}&scenario_id={scenario_id}&sign={sign}&ilrd={ilrd}

1. Taku会以 GET 方式请求开发者的回调URL，并拼接以下参数回传：

user_id={user_id}&trans_id={trans_id}&reward_amount={reward_amount}&reward_name={reward_name}&placement_id={placement_id}&extra_data={extra_data}&network_firm_id={network_firm_id}&adsource_id={adsource_id}&scenario_id={scenario_id}&sign={sign}&ilrd={ilrd}

开发者url自定义回调信息的占位符如下，注意

• 不一定要配置所有占位符，即需要哪些信息就配置哪些占位符
• 如果需要签名机制（即有配置：sign={sign}），那么涉及签名相关（见下面：sign签名规则说明）的所有占位符都需要配置
• 回调给开发者的url除了自定义配置信息外，某些情况还有可能额外返回人民币转美元汇率信息（例如：exch_rate_c2u=0.1375），不关注可忽略
• 使用开发者后台创建或编辑服务端激励广告位时，默认会回调一次开发者在后台配置的激励url，目的是为了一开始就检测开发者配置的url是否正常，即此时回调的url占位符是没有替换的并且会增加回调参数：is_test=1

1. sign签名规则说明

开发者在收到Taku的服务端激励回调时，可以通过sign对回调参数进行校验。

• Taku服务器按以下规则生成sign签名（不带ilrd)

sign =MD5("trans_id="+trans_id+"&placement_id="+placement_id+"&adsource_id="+adsource_id+"&reward_amount="+reward_amount+"&reward_name="+reward_name+"&sec_key="+sec_key)

• Taku服务器按以下规则生成sign签名（带ilrd)

如果回调URL中有 {ilrd} 参数，需要使用以下sign签名规则：

sign =MD5("trans_id="+trans_id+"&placement_id="+placement_id+"&adsource_id="+adsource_id+"&reward_amount="+reward_amount+"&reward_name="+reward_name+"&sec_key="+sec_key+"&ilrd="+ilrd)

• sign签名示例

sign签名示例如下：

sign=MD5(trans_id=xxxxxxxxxxxxxxxx&placement_id=b5b449fb3d89d7&adsource_id=56789&reward_amount=1&reward_name=coin&sec_key=cyvmwmzrqts7csphhexpqxqxxgljfisb&ilrd=abc)

1. 开发者回调URL收到Taku的服务端激励回调后，需给Taku服务器返回状态码200 或 601或 602 。Taku收到成功或失败状态码后，都不会重发服务端激励回调

1. Taku服务器发起服务端激励回调后2秒内无响应则视为超时，超时后会每隔一会（比如2秒，4秒，8秒等）重试发送激励回调。Taku最大重试5次还超时，则不再向开发者回调URL发起激励回调

3.3 分广告场景的服务端激励

为了满足开发者在不同的激励视频广告场景下发不同的激励，Taku允许开发者除了在不同的广告场景上设置不同的激励名称和激励数量，具体使用流程如下：

1. 打开激励视频广告位的服务端激励回调，并在回调URL中接收Taku回调的广告场景ID{scenario_id}
2. 在Taku后台的广告场景下设置激励数量和激励名称，参考如下：

1. 开发者在收到Taku的服务端激励回调时，根据广告场景ID{scenario_id}下发不同的激励

3.4 服务端激励规则快捷复用

为了减少开发者手动配置服务端回调规则的时间，Taku允许开发者快捷复用服务端回调规则，步骤如下：

1. 在高级功能的下拉界面中，进入服务端回调
2. 新建回调规则，编辑好后保存规则。

1. 在新建或修改广告位时，打开服务端回调按钮，选择对应规则，即可实现该规则的快捷复用。

4. Taku SDK接入

4.1 Taku Android SDK代码示例

Map localMap = new HashMap<>();
localMap.put(ATAdConst.KEY.USER_ID, "test_user_id");
localMap.put(ATAdConst.KEY.USER_CUSTOM_DATA, "test_user_data");
mRewardVideoAd.setLocalExtra(localMap);

mRewardVideoAd.load();

4.2 Taku iOS SDK代码示例

[[ATAdManager sharedManager] loadADWithPlacementID:placementId extra:@{kATAdLoadingExtraMediaExtraKey:@"test_user_data", kATAdLoadingExtraUserIDKey:@"test_user_id"} delegate:self];

4.3 Taku Unity SDK代码示例

Dictionary jsonmap = new Dictionary();

jsonmap.Add(ATConst.USERID_KEY, "test_user_id");
jsonmap.Add(ATConst.USER_EXTRA_DATA, "test_user_data");

ATRewardedVideo.Instance.loadVideoAd(placementId, jsonmap);

4.4 Taku Cocos2dx SDK代码示例

cocos2d::ValueMap extra;
extra[ATCocosSdk::KEY_USER_ID] = "test_user_id";
extra[ATCocosSdk::KEY_MEDIA_EXT] = "test_user_data";
ATCocosSdk::loadRewardedVideoAd(placementId, extra);

4.5 Taku CocosCreator SDK代码示例

var setting = {};
setting[ATRewardedVideoJSSDK.userIdKey] = "test_user_id";
setting[ATRewardedVideoJSSDK.userDataKey] = "test_user_data";
ATRewardedVideoJSSDK.loadRewardedVideo(placementId, setting);

4.6 Taku ReactNative SDK代码示例

var setting = {};
settings[ATRewardedVideoRNSDK.userIdKey] = "test_user_id";
settings[ATRewardedVideoRNSDK.userDataKey] = "test_user_data";
ATRewardedVideoRNSDK.loadAd(placementId, settings);

5. ILRD数据说明

6.常见问题

（1）Taku的服务端激励回调和三方平台的有什么区别

1）Taku的服务端激励回调会提供包括Taku ADX、三方平台预估eCPM等数据的激励回调。

若使用Taku ADX、交叉推广、直投广告等，在Taku设置服务端激励回调会更加准确。三方平台的服务端激励回调则是走三方平台的会更加准确。

2）Taku和三方平台的激励回调建议二者只选择配置一个。

例如若希望使用穿山甲的激励回调，则不需要在Taku后台创建。

（2）是否一定要配置服务端端激励回调

一般来说，若产品策略，需要针对不同的eCPM/广告场景下发不同的奖励，则需要配置服务端激励回调。

例如：希望给在特定广告场景观看了广告的用户发放特殊的奖励。

若没有这一类的需求，则可以不配置服务端端激励回调。