Rewarded Ad Server-Side Verification Integration Guide

A rewarded ad is an ad in which users obtain a reward by watching the ad content. The ad usually lasts 6~30s, and users can receive the reward after watching enough of the ad. Common rewards include game revival, claiming tokens, and so on. Currently, developers use the ad component's onClose callback to determine whether the user has finished watching the ad and met the reward conditions.

Server-side verification is an optional verification method. When the reward conditions are met, SUD OP SVR sends a request to the developer server to notify that the user has met the reward conditions and the reward can be granted. After receiving the request, the developer can perform validation on the server side, providing an additional protection mechanism for reward distribution to guard against client-side cheating.

Server-Side Verification

Flow Sequence Diagram

The overall flow is as follows:

1. The developer enables rewarded video server-side verification in the SUD OP console and fills in the callback URL, secret key, and other information;

2. The developer creates an ad component and fills in the corresponding parameters;

3. When the user watches the rewarded ad and meets the reward conditions, there are two callbacks:

   a. The front-end callback, i.e., the ad component's onClose callback;

   b. The server-side callback: SUD OP reports the event that the user has met the reward conditions to SUD OP SVR, which then forwards the request to the server-side interface configured by the developer.

4. Based on the callback result, the developer grants the reward to the user.

Compared with the front-end callback, the server-side callback may be delayed. For the sake of user experience, you can grant the reward when the front-end callback is received, and perform verification when the server-side callback is received, as a safeguard. If the reward itself is important and may affect the overall game progression, you can also wait until the server-side callback is received before granting the reward.

Enabling Server-Side Verification

1. In the SUD OP console, go to Business Capabilities - Traffic Owner and find "Server-Side Reward Callback"

2. Click to enable

3. Fill in the relevant configuration

Creating the Ad Component

For the creation and display logic of the rewarded video ad component, refer to the official documentation; there is no difference from the original flow.

For passing through custom verification fields, a new API is added on the rewarded video instance, which must be called before calling show.

Method name: setServerSideVerificationData

Parameter: customSSVData

Parameter type: Object

Definition of the parameters within customSSVData:

key	Type	Description
userId	string	User id
rewardItem	string	Reward item
rewardAmount	number	Reward quantity
customData	string	Custom data

Example:

const videoAd = sud.createRewardedVideoAd({
    adUnitId: 'XXX'
})

if (videoAd.setServerSideVerificationData) {
    videoAd.setServerSideVerificationData({
        userId: 'XXX',
        rewardItem: 'Coins',
        rewardAmount: 10,
        customData: 'XXX'
    })
}

videoAd.show()

Server-Side Callback Protocol

Protocol

See Rewarded Video Completion Callback for details.

Callback Retry Mechanism

The SUD OP console sets a 1s timeout for callbacks to the developer backend. If the developer callback does not return within the timeout, a retry is triggered, up to 3 times, at intervals of 15s, 22.5s, and 33.75s.

Q&A

Q1. Is the server-side verification capability mandatory? In what situations does it apply?

A. This capability was originally designed to help developers deal with possible cheating, such as directly skipping ads to obtain rewards. If a developer judges that the cheating risk of the current game is low, integration is not necessary.

Q2. Are there any risks/considerations when integrating this capability?

A. The server-side callback may be delayed. For the sake of user experience, it is recommended that developers grant the reward when the front-end callback is received, and then perform verification when the server-side callback is received, as a safeguard. If the reward itself is important and may affect the overall game progression, you can also wait until the server-side callback is received before granting the reward.