Server-Side Reward

1. Server-Side Reward Introduction

Server-Side Reward (Server-to-Server): Allows developers to decide whether to grant rewards to users who watch Rewarded Video ads. When a user finishes watching a Rewarded Video, the developer's server will be notified, and the developer will handle the reward distribution.

• Taku SDK < v5.7.56: Developers need to use Third-party Ad Platform Server-Side Reward
• Taku SDK >= v5.7.56: Developers can use Taku Server-Side Reward

Note: To ensure the accuracy of server-side rewards, for third-party ad platforms, it is strongly recommended that developers prioritize using the third-party ad platform's server-side reward callback. For Taku Adx, Direct Offer, and Cross Promotion, developers can directly use Taku's server-side reward callback. You can use the Network Firm ID to determine whether to accept only Taku's server-side reward callback:

1. Taku Adx Network Firm ID = 66

2. Taku Direct Offer Network Firm ID = 67

3. Taku Cross Promotion Network Firm ID = 35

2. Usage Flow for Third-Party Ad Platform Server-Side Reward

(1) Developers need to configure the callback URL of their own server in the third-party ad platform's backend.

(2) In code, developers pass UserID (unique user ID) and UserCustomData (user-defined data) through the Taku SDK API. These parameters will ultimately be passed to the developer via the callback URL.

(3) When a user finishes watching a Rewarded Video, the ad platform will notify the developer through the configured callback URL, and the developer will decide and grant the reward.

Ad platforms supporting server-side reward are listed below: (Clickable links lead to the ad platform's documentation on server-side reward. For non-clickable links, please log in to the ad platform's backend directly to configure the callback URL.)

2.1 Android

2.2 iOS

3. Taku Server-Side Reward Usage Instructions

1. Taku SDK >= v5.7.56 can use Taku server-side reward callbacks.
2. Taku SDK >= v5.7.78 and above supports returning impression-level data in Taku server-side reward callbacks (developers can add the {ilrd} parameter in the callback URL to retrieve the corresponding data).

3.1 Server-Side Reward Usage Flow

(1) Developers need to enable server-side reward on the Rewarded Video Ad Placement in the Taku backend and configure the callback URL.

(2) Developers need to pass UserID (unique user ID) and UserCustomData (user-defined data) in code through the Taku SDK API. These parameters will ultimately be passed to the developer via the callback URL.

(3) When a user finishes watching a Rewarded Video, the Taku platform will notify the developer through the configured callback URL, and the developer will decide and grant the reward.

3.2 Developer Server-Side Reward Integration Guide

(1) Developers need to enable server-side reward on the Rewarded Video Ad Placement in the Taku backend and configure the developer's server-side reward Callback URL, as shown below:

Example of a developer's Callback URL:

https://www.takuad.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}

(2) Taku will request the developer's Callback URL via GET method, appending the following parameters:

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) The placeholders for the developer's custom callback URL information are as follows. Note:

1. You do not need to configure all placeholders; configure only those for the information you need.
2. If the signature mechanism is required (i.e., configured with sign={sign}), then all placeholders involved in the signing process (see below: sign Signature Rules) must be configured.
3. In addition to the custom configured information, the callback URL sent to the developer may sometimes include additional RMB-to-USD exchange rate information (e.g., exch_rate_c2u=0.1375), which can be ignored if not needed.
4. When creating or editing a server-side reward Ad Placement in the developer backend, Taku will default to calling back the reward URL configured in the backend once. This is to immediately check whether the developer-configured URL is working properly. In this callback, the URL placeholders are not replaced, and an additional callback parameter is_test=1 is appended.

(4) sign Signature Rules Description

When receiving Taku's server-side reward callback, developers can verify the callback parameters using the sign.

1. Taku server generates the sign signature as follows (without 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)

2. Taku server generates the sign signature as follows (with ilrd):

If the callback URL includes the {ilrd} parameter, the following sign signature rule must 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)

(5) sign Signature Example

sign signature example:

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

(6) After the developer's callback URL receives Taku's server-side reward callback, it must return a status code of 200 or 601 or 602 to the Taku server. After Taku receives a success or failure status code, it will not resend the server-side reward callback.

Special note: The callback data may sometimes be very large (especially when ilrd is included). Developers should ensure that the GET callback URL length limit is removed, otherwise the developer's server may return a 414 error (for example, when using nginx, which has a default length limit).

If there is no response within 2 seconds after the Taku server initiates the server-side reward callback, it is considered a timeout. After a timeout, Taku will retry sending the reward callback at intervals (e.g., 2 seconds, 4 seconds, 8 seconds, etc.). If Taku has retried a maximum of 5 times and still times out, it will no longer send the reward callback to the developer's callback URL.

3.3 Per-Ad-Scene Server-Side Reward

To support developers granting different rewards in different Rewarded Video ad scenes, Taku allows developers to set different reward names and reward amounts for different ad scenes. The specific usage flow is as follows:

(1) Enable the server-side reward callback for the Rewarded Video Ad Placement and receive the Taku callback's Ad Scene ID {scenario_id} in the callback URL.

(2) Set the reward amount and reward name under the ad scene in the Taku backend, as shown below:

(3) When receiving Taku's server-side reward callback, the developer grants different rewards based on the Ad Scene ID {scenario_id}.

3.4 Quick Reuse of Server-Side Reward Rules

To reduce the time developers spend manually configuring server-side reward callback rules, Taku allows developers to quickly reuse server-side reward callback rules. The steps are as follows:

(1) In the Advanced Features dropdown menu, go to Server-Side Callback.

(2) Create a Callback Rule, edit it, and save the rule.

(3) When creating or editing an Ad Placement, enable the server-side callback toggle and select the corresponding rule to quickly reuse that rule.

4. Taku SDK Integration

4.1 Taku Android SDK Code Sample

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 Taku iOS SDK Code Sample

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

4.3 Taku Unity SDK Code Sample

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 Taku Cocos2dx SDK Code Sample

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 Taku CocosCreator SDK Code Sample

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

4.6 Taku ReactNative SDK Code Sample

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

5. ILRD Data Description

Note: The ilrd parameter is only for behavioral data analysis reference and cannot be directly used as the basis for reward distribution. If you need to use impression revenue data for reward share calculations, please use impression revenue data. Reference documents: Impression Ad Source eCPM Encryption, Ad Impression Server-Side Callback (S2S)

6. FAQ

(1) What is the difference between Taku's server-side reward callback and third-party platforms' callbacks?

1. Taku's server-side reward callback provides reward callbacks that include data such as Taku ADX and third-party platform estimated eCPM.

If using Taku ADX, Cross Promotion, Direct Offer ads, etc., configuring the server-side reward callback in Taku will be more accurate. Third-party platform server-side reward callbacks will be more accurate when going through the respective third-party platform.

2. To ensure the accuracy of reward callbacks as much as possible, it is recommended to use client-side reward callbacks, third-party server-side reward callbacks, and Taku server-side reward callbacks simultaneously, and perform parameter consistency verification across all three callbacks.