服务端激励

1. 服务端激励介绍

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

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

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

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

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

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

2.1 Android

2.2 iOS

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

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

3.1 服务端激励使用流程

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

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

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

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

https://www.toponad.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. TopOn会以 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签名规则说明

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

• TopOn服务器按以下规则生成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)

• TopOn服务器按以下规则生成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收到TopOn的服务端激励回调后，需给TopOn服务器返回状态码200 或 601或 602 。TopOn收到成功或失败状态码后，都不会重发服务端激励回调。

特别注意：回调的数据有时可能很大（特别是包含ilrd时候），开发者应保证去除GET回调Url的长度限制，否则开发者服务器可能会报414错误（例如使用了nginx, 默认有长度限制）

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

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

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

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

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

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

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

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

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

4. TopOn SDK接入

4.1 TopOn 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 TopOn iOS SDK代码示例

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

4.3 TopOn 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 TopOn 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 TopOn CocosCreator SDK代码示例

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

4.6 TopOn ReactNative SDK代码示例

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

5. ILRD数据说明