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:

Network Firm ID of TopOn Adx=66
Network Firm ID of TopOn direct advertising =67
TopOn cross-promotion Network Firm ID=35

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

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

Advertising platform	Reference URL	Remarks
Facebook	https://developers.facebook.com/docs/audience-network/guides/ad-formats/rewarded-video/android
Admob & Google Ad Manger	https://support.google.com/admob/answer/9603226?hl=zh-Hans&ref_topic=7382891
Applovin	-	Please log in to the Applovin background to set the callback URL
Mintegral	http:/ /cdn-adn.rayjump.com/cdn-adn/v2/markdown_v2/index.html?file=sdk-m_sdk-android&lang=cn
Mopub	https:// developers.mopub.com/publishers/android/rewarded-video/#passing-custom-data
ironSource	https://developers.ironsrc.com/ironsource-mobile/android/ advanced-settings/#step-2
UnityAds	http://unityads.unity3d.com/help/resources/s2s-redeem-callbacks
Vungle	https://support.vungle.com/hc/en-us/articles/204374244-Setting-Up-Rewarded-Ads#server-to-server -s2s-callbacks-0-0
AdColony	https://github.com/AdColony/AdColony-Android-SDK/wiki/Showing-Rewarded -Interstitial-Ads#server-side-rewards
TT (CSJ)	https://www.pangle.cn/union/media/ union/download/detail?id=4&docId=5de8d9b725b16b00113af0e5&osType=android#5d15f2
AppNext	https://developers.appnext.com/ docs/appnext-android-rewarded-fullscreen#server-side-postback---rewarded-video
Ogury	https://ogury-ltd.gitbook.io/android/ad-formats/opt-in-video-ad
Huawei	-	Please log in to the Huawei backend to set the callback URL
Tencent Advertising	https://developers.adnet.qq.com/doc/android/union/union_reward_video	Please log in Tencent Advertising background settings callback URL TopOn SDK v5.7.8 and above are supported
Sigmob	https://doc.sigmob.com/#/Sigmob%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/%E5%B9%B3%E5%8F%B0%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/%E6%BF%80%E5%8A%B1%E8%A7%86%E9%A2%91%E6%9C%8D%E5%8A%A1%E7%AB%AF%E9%AA%8C%E8%AF%81/	Starting from version v5.7.40, supports the incoming of customData, and notifies the developer through the callback URL set by the developer in the form of a Json string (Key is user_custom_data, Value is customeData)
Kuaishou	https://static.yximgs.com/udata/pkg/KS-Android-KSAdSDk/doc/4701b963d40a77bc0f45fd71d30b57da.pdf	Supported from v5.7.25 version, must be used simultaneously before the ad is loaded Pass in userId, customData
Baidu	https://union.baidu.com/miniappblog/2020/12/01/newAndroidSDK/

2.2 iOS

Advertising platform	Reference URL	Remarks
Facebook	https://developers.facebook.com/docs/audience-network/guides/ad-formats/rewarded-video/ios
Admob & Google Ad Manger	https://developers. google.com/admob/ios/rewarded-video-ssv
Applovin	https://dash.applovin.com/docs/integration#iosRewardedVids
Mintegral	http://cdn-adn.rayjump.com/cdn-adn/v2/markdown_v2/index.html?file=sdk-m_sdk-ios&lang=cn
ironSource	https://developers.ironsrc.com/ironsource-mobile/ios/advanced-settings-2/#step-3
Vungle	https://support.vungle.com/hc/en-us/articles/204374244-Setting-Up-Rewarded-Ads#server-to-server- s2s-callbacks-0-0
AdColony	https://github.com/AdColony/AdColony-iOS-SDK/wiki/Showing-Rewarded- Interstitial-Ads#server-side-rewards
TT (CSJ)	https://www.pangle.cn/union/media/union /download/detail?id=23 &docId=5de8d72ab1afac00129330e6&osType=ios#620104
AppNext	https://developers.appnext.com/docs/appnext-ios- rewarded-fullscreen#server-side-postback---rewarded-video-ad
Ogury	https://ogury-ltd.gitbook.io/ios/ad-formats/ opt-in-video-ad
Nend	Click to view
Sigmob	https://doc.sigmob.com/#/Sigmob%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/%E5%B9%B3%E5%8F%B0%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/%E6%BF%80%E5%8A%B1%E8%A7%86%E9%A2%91%E6%9C%8D%E5%8A%A1%E7%AB%AF%E9%AA%8C%E8%AF%81/	Starting from version v5.7.41 , supports the incoming of customData, and notifies the developer through the callback URL set by the developer in the form of a Json string (Key is user_custom_data, Value is customeData)
UnityAds	https://unityads. unity3d.com/help/resources/s2s-redeem-callbacks
Tapjoy	-	Please log in to the Tapjoy backend to set the callback URL
Tencent Advertising	https://developers.adnet.qq.com/doc/ios/union/union_reward_video	Please log in to the Tencent Advertising backend to set the callback URL TopOn SDK v5.7.8 and above are supported
Kuaishou	https://static. yximgs.com/udata/pkg/KSAdSDKTarGz/doc/ksadsdk-iOS-readme-ad-3.3.9.pdf
Baidu	https://union.baidu.com/miniappblog/2020/08 /11/iOSSDK/

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

Developers need to turn on server-side reward in the rewarded video advertising space in the TopOn backend and set the callback URL address
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
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}

Parameter	Description	Remarks
{user_id}	User ID	Set by the developer through the TopOn SDK API
{extra_data}	User business parameters	Set by the developer through the TopOn SDK API
{trans_id}	The trans_id generated by the TopOn server is unique	It is strongly recommended that developers verify whether trans_id has been issued rewards before the server issues rewards to ensure Avoid repeated issuance of rewards to the same trans_id
{reward_name}	reward name	Set in the developer backend ( Supports advertising slot or Advertising scene settings)
{reward_amount}	reward quantity	Set in the developer backend ( Supports advertising slot or Advertising scene settings)
{placement_id}	TopOn ad slot ID	-
{network_firm_id}	TopOn aggregated advertising platform ID	[Special attention] 1). If you need to use server-side rewards while using TopOn Adx, direct investment, and cross-promotion: For third-party advertising platforms, it is recommended that you give priority to the server-side reward callbacks of the third-party advertising platform; for TopOn Adx, direct investment, and cross-promotion, You can use TopOn's server-side reward callbacks. 2). You can determine whether to only accept 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 View TopOn advertising platform ID list
{adsource_id}	TopOn ad source ID	-
{scenario_id}	TopOn advertising scene ID	Set by developer through TopOn SDK API
{package_name}	The package name or Bundle ID of the developer's application	Get the developer's application package name or Bundle ID from TopOn SDK
{ platform}	System platform, Android or iOS	Return according to the following enumeration types, 1: Android, 2: iOS
{ilrd}	Display-level data for TopOn SDK callback. Data For json string	TopOn SDK v5.7.78 and above are supported. TopOn SDK provides developers with display-level data when calling back reward video OnReward. Specific data format reference
{sign}	Signature information	Reference signature rule description

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

Parameters	Example
trans_id	xxxxxxxxxxxxxxxx
placement_id	b5b449fb3d89d7
adsource_id	56789
reward_amount	1
reward_name	coin
sec_key	cyvmwmzrqts7csphhexpqxqxxgljfisb
ilrd	abc

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

Return status code	Description
200	Success
601	Signature verification failed
602	Other failures

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

Variable	Type	Description
network_firm_id	int	Get the corresponding information of the advertising platform ID, used to distinguish advertising platforms
adsource_id	string	Get the advertising source ID. You can use the advertising source ID in the developer backend or TopOn Open API Query specific Network information
adsource_index	int	Get the sorting of the current advertising source in WaterFall(starting from 0)
adsource_price	dounble	Get ECPM , the unit can be obtained through "currency"
adsource_isheaderbidding	int	Whether it is the advertising source for header bidding, 1: Yes, 2: No
id	string	Get every time independent ID generated when displaying ads
publisher_revenue	double	Get impression revenue
currency	string	Get the currency unit, for example: "USD"
country	string	Get the country code, for example: "CN"
adunit_id	string	Get TopOn ad slot ID
adunit_format	string	Get the ad type, including: " Native", "RewardedVideo", "Banner" "Interstitial", "Splash"
precision	string	Get ECPM accuracy "publisher_defined": The eCPM defined by the developer for the advertising source in the TopOn backend (eCPM for interactive promotion also belongs to this type) "estimated": TopOn's estimated eCPM (auto eCPM) "exact": eCPM of Header Bidding real-time bidding
network_type	string	Get Network type "Network": Third-party advertising platform "Cross_Promotion": Cross-promotion "Adx"：TopOn Adx
network_placement_id	string	Get Network's advertising space ID
ecpm_level	int	Get the eCPM level of the advertising source, The header bidding ad source defaults to 0
segment_id	int	Get the traffic group ID
scenario_id	string	Get the advertising scene ID, Only supported by Rewarded Video&Interstitial (starting from v5.7.20, supports Native&Banner)
scenario_reward_name	string	Get the reward name of the advertising scene, Only supported by Rewarded Video
scenario_reward_number	int	Get the reward number of the advertising scene, Only supported by Rewarded Video
sub_channel	string	Get sub-channel information
channel	string	Get channel information
custom_rule	Dictionary<string,object>	Gets a Json string of custom rules for the Placement+App dimension