reward video server reward (S2S) instructions

1. Introduction to server-side rewards

Server-to-Server: allows developers to decide whether to issue rewards to users who watch reward videos. When the user watches the reward 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 rewards
• TopOn SDK > = v5.7.56 Developers can use TopOn server-side rewards

Note: In order to ensure the accuracy of server-side rewards, developers are recommended to use the server-side reward callbacks of third-party advertising platforms first. For TopOn Adx, direct investment, and cross-promotion, developers can directly use TopOn's server-side reward callbacks. You can determine whether to accept only TopOn server-side reward callbacks based on the Network Firm ID:

1. Network Firm ID of TopOn Adx=66
2. Network Firm ID of TopOn direct advertising =67
3. TopOn cross-promotion Network Firm ID=35

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

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 unique ID), UserCustomData (user-defined data). These parameters will eventually be passed to the callback URL Notify developers
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 rewards.

The advertising platforms that support server-side rewards are as follows : (You can click to jump to the advertising platform’s documentation on server-side rewards. 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 rewards

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

3.1 Server-side reward usage process

1. Developers need to turn on server-side reward 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 reward 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 reward Access Guide

1. Developer needs Turn on the server-side reward for the rewarded video ad space in the TopOn backend, and set the developer's server-side reward 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 request the developer's GET method 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. Explanation of signature rules

When developers receive TopOn's server-side reward 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

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

sign signature example 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's callback URL receives TopOn's server-side reward callback, it needs to give TopOn The server returns status code 200 or 601 or 602. After TopOn receives the success or failure status code, it will not resend the server-side reward callback

6. If there is no response within 2 seconds after the TopOn server initiates the server-side reward callback, it will be considered a timeout. , after timeout, the reward callback will be retried 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 reward callback to the developer callback URL

3.3 Server-side rewards for advertising scenarios

In order to satisfy developers in issuing different rewards under different rewarded video advertising scenarios , TopOn allows developers to set different reward names and reward amounts in different advertising scenarios. The specific usage process is as follows:

1. Open the rewarded video advertising space The server fires the callback and receives the TopOn callback in Callback URLAdvertising scene ID{scenario_id}

2. In TopOn In the background advertising scene, set reward quantity and reward name, refer to the following:

3. When the developer receives TopOn's server-side reward callback, the developer will use the advertising scene ID{scenario_id} distribute different rewards

3.4 Quick replication of server-side reward rules Us

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:

1. In Advanced functions In the drop-down interface, enter Server callback

2. Create a new Callback rule and save the rule after editing.

3. When creating or modifying an ad slot, open the server callback button and select the corresponding rule, that is Quick reuse of this rule can be achieved.

4.TopOn SDK access

4.1 TopOn Android SDK code example

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 TopOn iOS SDK code example

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

4.3 TopOn Unity SDK code example

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 TopOn Cocos2dx SDK code example

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 code example

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

4.6 TopOn ReactNative SDK code example

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

5.ILRD data description