Server-side rewarded

1. Introduction to server-side incentives

Server-to-Server: allows developers to decide whether to issue rewards to users who watch incentive videos. When the user watches the incentive video, the developer's server will be notified, and the developer will issue the reward itself

• TopOn SDK < v5. 7.56 Developers need to use Third-party advertising platform server-side incentives
• TopOn SDK >= v5.7.56 Developers can use TopOn server-side incentives

Note: In order to ensure the accuracy of server-side incentives, it is recommended that developers give priority to using the server-side incentive callbacks of third-party advertising platforms. For TopOn Adx, direct investment, and cross-promotion, developers can directly use TopOn's server-side incentive callbacks. You can determine whether to accept only TopOn server-side incentive callbacks based on the Network Firm ID:

1 .TopOn Adx’s Network Firm ID=66

2.TopOn Direct Advertising Network Firm ID=67

3.TopOn cross-promotion Network Firm ID=35

2. The usage process of third-party advertising platform server-side incentives

1. Developers need to go to the backend of the third-party advertising platform to set the callback URL address of the developer's own server.
2. Developers pass in UserID (user's unique ID) and UserCustomData (user-defined data) in the code through the API of TopOn SDK. These parameters will eventually be notified to the developer through the callback URL.

3. When the user watches the rewarded video, the advertising platform will notify the developer through the set callback URL address, and the developer will make its own judgment and issue the reward.

The advertising platforms that support server-side incentives are as follows: (You can click to jump to the advertising platform's documentation on server-side incentives. If you cannot jump, please log in to the advertising platform backend directly to set the callback URL)

2.1 Android

2.2 iOS

3. Instructions for using TopOn server-side incentives

• TopOn SDK >= v5.7.56 You can use TopOn service incentive callback
• TopOn SDK >= v5.7.78 Versions and above support returning display-level data in the TopOn service incentive callback (developers can add the {ilrd} parameter to the callback URL to obtain the corresponding data)

3.1 Server-side incentive usage process

1. Developers need to turn on server-side incentives in the rewarded video advertising space in the TopOn backend and set the callback URL address
2. Developers need to pass the TopOn SDK in the code The API passes in UserID (user’s unique ID) and UserCustomData (user-defined data). These parameters will eventually be notified to the developer through the callback URL
3. When the user finishes reading the incentive When making a video, the TopOn platform will notify the developer through the set callback URL address, and the developer will make their own judgment and issue rewards

3.2 Developer's Server-Side Incentive Access Guide

1. Developer You need to enable server-side incentives for the rewarded video advertising space in the TopOn backend, and set the developer's server-side incentives Callback URL, the example is as follows:

2. Developer's Callback URL an example is as follows:

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}

3. TopOn will be in GET modeRequest the developer's Callback URL and splice the following parameters back:

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}

4. signSignature rule description

When developers receive TopOn's server-side incentive callback, they can verify the callback parameters through sign.

• TopOn server generates sign signature (without ilrd) according to the following rules

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 server generates sign signature (with ilrd) according to the following rules

If there is {ilrd} parameter in the callback URL, the following sign signing rules need to be used:

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)

• Signature example

Signature example is as follows:

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

5. After the developer callback URL receives TopOn's server-side incentive callback, it needs to return status code 200 or 601 or 602 to the TopOn server. After TopOn receives the success or failure status code, it will not resend the server-side incentive callback.

6. If there is no response within 2 seconds after the TopOn server initiates the server-side incentive callback, it will be considered a timeout. After the timeout, it will retry sending the incentive callback every once in a while (such as 2 seconds, 4 seconds, 8 seconds, etc.). If TopOn retries for a maximum of 5 times and times out, it will no longer initiate an incentive callback to the developer's callback URL.

3.3 Server-side incentives based on advertising scenarios

1. In order to allow developers to issue different incentives in different rewarded video advertising scenarios, TopOn allows developers to set different incentive names and incentive quantities in different advertising scenarios. The specific usage process is as follows:
2. 1. Open the server-side incentive callback of the rewarded video ad slot, and receive the advertising scene ID {scenario_id} of the TopOn callback in the callback URL.
3. 2. Set the incentive quantity and incentive name in the advertising scene in the TopOn backend, refer to the following：

1. When developers receive TopOn's server-side incentive callback, they will issue different incentives based on the advertising scene ID {scenario_id}.

3.4 Quick reuse of server-side incentive rules

1. In order to reduce the time developers spend manually configuring server callback rules, TopOn allows developers to quickly reuse server callback rules. The steps are as follows:
2. 1. In the drop-down interface of advanced functions, enter the server callback
3. 2. Create a new callback rule and save the rule after editing.

1. When creating or modifying an ad slot, open the server callback button and select the corresponding rule to quickly reuse the rule.

4. Code examples

4.1 Android

Map<String, Object> 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 iOS

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

4.3 Unity

Dictionary<string,string> jsonmap = new Dictionary<string,string>();

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

ATRewardedVideo.Instance.loadVideoAd(placementId, jsonmap);

4.4 Cocos2dx

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 CocosCreator

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

4.6 ReactNative

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

5. ILRD data description