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

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'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

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< /td>
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
Pangolin (Pangle)	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
-	Please log in to the Huawei backend to set the callback URL
Tencent	https://developers.adnet.qq.com/doc/android/union/union_reward_video	Please Log in to the Tencent Advertising backend and set the callback URL TopOn SDK v5.7.8 and above are supported
Sigmob	https://support.sigmob.com/#/%E5%B9%B3%E5 %8F%B0%E6%93%8D%E4%BD%9C%E6%8C%87%E5%8D%97/Sigmob%E5%8F%98%E7%8E%B0/%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, required before the ad is loaded At the same time, 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
Pangolin (Pangle)	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://support.sigmob.com/#/%E5%B9%B3%E5%8F%B0%E6%93 %8D%E4%BD%9C%E6%8C%87%E5%8D%97/Sigmob%E5%8F%98%E7%8E%B0/%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	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< /td>
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 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

Developers need to turn on server-side incentives 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 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}

Parameters	Description	Remarks
{user_id}	User ID	User ID via TopOn SDK API settings
{extra_data}	User business parameters	Set by developers through TopOn SDK API
{trans_id}	trans_id generated by TopOn server , unique	Strongly recommended for development The user verifies whether the trans_id has been issued incentives before the server issues incentives to avoid repeated issuance of incentives to the same trans_id
{reward_name}	Incentive name	Set in the developer backend (supports advertising slot or Advertising scene settings)
{reward_amount}	Incentive amount	Set in the developer backend (supports advertising slot or Advertising scene settings)
{placement_id}	TopOn Ad Placement ID	-
{network_firm_id}	TopOn aggregated advertising platform ID	[Note] 1. If you need to use server-side incentives while using TopOn Adx, direct investment, or cross-promotion: For third-party advertising platforms, it is recommended that you give priority to the server-side incentives of the third-party advertising platform Callback; for TopOn Adx, direct investment, and cross-promotion, you can use TopOn's server-side incentive callback. 2. You can judge whether to only accept TopOn server-side incentive 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 View TopOn advertising platform ID list
{adsource_id}	TopOn ad source ID	-
{scenario_id}	TopOn advertising scene ID	Set by developer via TopOn SDK API
{package_name }	The package name or Bundle ID of the developer's application	Obtain the developer's application package name or Bundle ID from TopOn SDK
{platform}	System platform, Android or iOS	Press The following enumeration types are returned, 1: Android, 2: iOS
{ilrd}	TopOn SDK v5.7.78 and above are supported. TopOn SDK provides developers with display-level data when calling back incentive video OnReward. Specific data format reference
{sign}	Signature information	Refer to signature rule description

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

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

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.

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

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:
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.
2. Set the incentive quantity and incentive name in the advertising scene in the TopOn backend, refer to the following：

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

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 the drop-down interface of advanced functions, enter the server callback
2. Create a new callback rule and save the rule after editing.

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

Value	Type	Description
network_firm_id	int	Get the ID corresponding to the advertising platform, which is used to distinguish the advertising platform
adsource_id	int	Get the ad source ID. You can query the specific network information through the ad source ID in the developer's backstage or TopOn Open API
adsource_index	int	Get the sort of the current ad source in WaterFall (starting from 0)
adsource_price	dounble	Get ECPM, the unit can be obtained by "currency"
adsource_isheaderbidding	int	Whether it is the ad source of head auction, 1: yes, 2: no
id	int	Get a unique ID generated every display ad
publisher_revenue	double	Get impression revenue
currency	String	Get currency unit, for example: "USD"
country	String	Get country code, for example: "CN"
adunit_id	String	Get TopOn placement ID
adunit_format	String	Get ad types, including: "Native"、"RewardedVideo"、"Banner""Interstitial"、"Splash"
precision	String	Get eCPM precision "publisher_defined"：The eCPM defined by the developer for the ad source in the TopOn backend（Cross-promoted eCPM also belongs to this type) "estimated": TopOn's estimated eCPM（auto eCPM) "exact"：Header Bidding eCPM for 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 the ad placement ID of a third-party advertising platform
ecpm_level	int	Get the eCPM level of the ad source，Head bidding ad source defaults to 0
segment_id	int	Get segment ID
scenario_id	String	Get Advertising Scene ID，Only Rewarded Video and Interstitial support (Starting from v5.7.20, Support Native and Banner)
scenario_reward_name	String	Get the reward name of the advertising scene，Only Rewarded Video support
scenario_reward_number	int	Get the number of reward for the advertising scene，Only Rewarded Video support
sub_channel	String	Get sub-channel information
channel	String	Get Channel Information
custom_rule	String	Get the Json string of the Placement + App dimension custom rule

Advanced Features