Help Center/Details/

Rewarded video

Introduction

Incentive video advertisements need to allow users to actively choose to watch. The effect of the advertisement is to issue rewards to users after watching the video advertisement.
Usage scenarios include but are not limited to:

  1. Watch video ads in games and other apps to get in-game coins, etc.;
  2. Integral application access;
    Supported ad sizes: Full screen horizontal screen (aspect ratio 16:9), full screen vertical screen (aspect ratio 9:16). Android does not currently support gravity rotation

Authority

Template rendering of rewarded video ads: Provided by default
SDK rendering rewarded video ads: has been recycled and no longer provides creation

Request method

Remarks: There is no difference in the advertising request method for template rendering rewarded video and SDK rendering rewarded video, only the difference in request parameters.
In the incentive video request method of template rendering, the setExpressViewAcceptedSize parameter needs to be set. The value set is greater than 0.

Create TTAdNative object

TTAdNative mTTAdNative=TTAdSdk.getAdManager().createAdNative(this);

Template rendering request AdSlot

AdSlot adSlot = new AdSlot.Builder()
        .setCodeId(codeId)
        .setRewardName("金币") //奖励的名称 选填
        .setRewardAmount(3)  //奖励的数量 选填
        //模板广告需要设置期望个性化模板广告的大小,单位dp,激励视频场景,只要设置的值大于0即可
        且仅是模板渲染的代码位ID使用,非模板渲染代码位切勿使用
        .setExpressViewAcceptedSize(500,500)
        .setUserID("tag123")//tag_id
        .setMediaExtra("media_extra") //附加参数
        .setOrientation(orientation) //必填参数,期望视频的播放方向:TTAdConstant.HORIZONTAL 或 TTAdConstant.VERTICAL
        .build();

SDK rendering request AdSlot

AdSlot adSlot = new AdSlot.Builder()
        .setCodeId(codeId)
        .setRewardName("金币") //奖励的名称 选填
        .setRewardAmount(3)  //奖励的数量 选填
        .setUserID("tag123")//tag_id
        .setMediaExtra("media_extra") //附加参数
        .setOrientation(orientation) //必填参数,期望视频的播放方向:TTAdConstant.HORIZONTAL 或 TTAdConstant.VERTICAL
        .build();

Parameter description

Method Description
setCodeId() The code ID created by the platform starts with 9 and 9 digits
setRewardName() The reward name (optional) is consistent with the creation code. Obsolete in 3300 and above
setRewardAmount() The reward quantity (optional) is the same as the one filled in the creation code position. Obsolete in 3300 and above
setExpressViewAcceptedSize() Set the size of the requested template creative. Unit: dp, the value set is greater than 0 (required for template ads)
setUserID() tag_id
setMediaExtra() User transparent transmission information (optional) only supports a single json object format, and json objects cannot be nested
setOrientation() It is expected that the playback direction of the video is consistent with the direction checked in the creation code bit (required)

Note: The template rendering code bit setExpressViewAcceptedSize is required, and the SDK template rendering code bit ID should not be passed.

Request ad

TTAdNative.loadRewardVideoAd(AdSlot var1, @NonNull TTAdNative.RewardVideoAdListener var2)Load rewarded video ads asynchronously
mTTAdNative.loadRewardVideoAd(adSlot, new TTAdNative.RewardVideoAdListener() {
            @Override
            public void onError(int code, String message) {
                Log.e(TAG, "Callback --> onError: " + code + ", " + String.valueOf(message));
                TToast.show(RewardVideoActivity.this, message);

            }

            //视频广告加载后,视频资源缓存到本地的回调,在此回调后,播放本地视频,流畅不阻塞。
            @Override
            public void onRewardVideoCached() {
                Log.e(TAG, "Callback --> onRewardVideoCached");
                mIsLoaded = true;
                TToast.show(RewardVideoActivity.this, "Callback --> rewardVideoAd video cached");
            }

            @Override
            public void onRewardVideoCached(TTRewardVideoAd ad) {
                Log.e(TAG, "Callback --> onRewardVideoCached");
                mIsLoaded = true;
                TToast.show(RewardVideoActivity.this, "Callback --> rewardVideoAd video cached");
                ad.showRewardVideoAd(RewardVideoActivity.this, TTAdConstant.RitScenes.CUSTOMIZE_SCENES, "scenes_test");

            }


TTRewardVideoAd

Method Parameter Description
void setRewardAdInteractionListener(TTRewardVideoAd.RewardAdInteractionListener var1) TTRewardVideoAd.RewardAdInteractionListener var1 Method description: Register a rewarded video ad callback
Parameter description: listener interactive listener
void setRewardPlayAgainInteractionListener(TTRewardVideoAd.RewardAdInteractionListener var1) TTRewardVideoAd.RewardAdInteractionListener var1 Method description: Register for rewarded video and watch another advertisement callback
Parameter description: listener interactive listener
void setDownloadListener(TTAppDownloadListener var1) TTAppDownloadListener var1 Method description: download callback of registered advertisement
Parameter description: listener download status callback
int getInteractionType() NULL Method description:
-2 open in the browser (common type
-3 landing page (common type)
-4: application download,
-5: make a call
-1 unknown Type Parameter description:NULL
@MainThreadvoid showRewardVideoAd(Activity var1) Activity var1 Method description: Display rewarded video advertisement interface
Parameter description: host activity
Map<String, Object> getMediaExtraInfo() NULL Method description: return additional advertising information
Parameter description: NULL
void showRewardVideoAd(Activity var1, RitScenes var2, String var3) Activity var1, RitScenes var2, String var3 Method description: Display rewarded video advertisement interface
Parameter description:
Activity: host activity
RitScenes: scene of advertisement display
String: custom scene information when advertisement display scene is CUSTOMIZE_SCENES
void setShowDownLoadBar(boolean var1) boolean var1 Method description: set display download bar
Parameter description: boolean type
- True
- false
int getRewardVideoAdType() NULL Method description: get the interactive type of the advertisement
AD_TYPE_UNKNOWN //unknown type
AD_TYPE_COMMON_VIDEO //normal video type
AD_TYPE_PLAYABLE_VIDEO //video + playable type
AD_TYPE_PLAYABLE //playable type
Parameter description: NULL
long getExpirationTimestamp() NULL Method description: Return the expiration time of the validity period. After this point in time, the advertisement is regarded as expired.
Parameter description: NULL
public interface RewardAdInteractionListener () NULL RewardAdInteractionListener description
RewardAdInteractionListener
Parameter Description
onAdShow() Ad show callback
onAdVideoBarClick() Advertisement download bar click callback
onAdClose() Ad close callback
onVideoComplete() Video playback complete callback
onSkippedVideo() Skip video playback callback
onRewardVerify() Reward verification callback, Developers need to issue rewards in this callback

RewardVideoAdListener

Method Description
onError() Advertisement request failed callback The returned error code (code) indicates the reason why the advertisement request failed. For details, please see链接
onRewardVideoCached() Callback for the completion of the local loading of the ad video, the local video can be played directly after this callback
onRewardVideoCached(TTRewardVideoAd ad) The callback for the completion of the local loading of the ad video, the local video can be played directly after the callback, and the parameter object can be used to play directly
onRewardVideoAdLoad() Callback when ad loading is complete

Note: In order to ensure the smooth playback of advertising video, it is recommended to call the showRewardVideoAd method in the main thread to display the advertisement after the onRewardVideoCached callback is loaded. After displaying the advertisement, set the advertisement object to null in time

//当mIsLoaded标识为true 代表广告视频本地加载完整 可直接开启一个主线程处理showRewardVideoAd
if (mttRewardVideoAd != null&&mIsLoaded) {
       //展示广告,并传入广告展示的场景
       mttRewardVideoAd.showRewardVideoAd(RewardVideoActivity.this, TTAdConstant.RitScenes.CUSTOMIZE_SCENES, "scenes_test");
       mttRewardVideoAd = null;
     } else {
        TToast.show(RewardVideoActivity.this, "请先加载广告");
 }

Advertising interaction listener

RewardAdInteractionListener mttRewardVideoAd.setRewardAdInteractionListener(new TTRewardVideoAd.RewardAdInteractionListener() {
	//广告的下载bar点击回调
    @Override
    public void onAdVideoBarClick() {
       
    }
	//视频广告关闭回调
    @Override
    public void onAdClose() {
       
    }
    //视频播放完成回调
    @Override
    public void onVideoComplete() {
       
    }
	//视频广告播放错误回调
    @Override
    public void onVideoError() {

    }

    //视频播放完成后,奖励验证回调,rewardVerify:是否有效,rewardAmount:奖励梳理,rewardName:奖励名称,code:错误码,msg:错误信息
    @Override
    public void onRewardVerify(boolean rewardVerify, int rewardAmount, String rewardName,int code,String msg) {

    }
	//视频广告跳过回调
    @Override
    public void onSkippedVideo() {

    }
   //视频广告展示回调
    @Override
    public void onAdShow() {

    }
});

onRewardVerify Callback description:

  1. The onRewardVerify callback only verifies the video playback status or progress without the user's server reward verification. If the video is played 90% or the playback fails due to an abnormal player, the CSJ will call back onRewardVerify with rewardVerify=true.
  2. In the case of using server-side reward verification, the onRewardVerify callback returns the result of the developer's server-side verification.

Summary: The onRewardVerify callback is only a result of the video playback status or the result returned by the developer, and does not represent advertising business indicators such as whether the playback is billed or not.

onRewardVerify parameter description
Parameter Description
rewardVerify Is it valid
rewardAmount The number of rewards, the value configured when the media platform creates the code bit
rewardName Reward name, the name configured when the media platform creates the code bit
code Error code. New in version 3300
msg msg error message. New in version 3300

Note: Add int code, String msg parameters in the onRewardVerify callback method of SDK3300 version

Need server judgment: the award can be issued based on rewardVerify as the judgment condition
No server judgment is required: rewardVerify returns true by default. The code bit of the test status rewardVerify returns false by default.

Reward distribution mechanism

Refer to this document for reward distribution logic: Link

Server to server callback

The server-to-server callback allows you to determine whether to provide rewards to users who watch the ad. When the user has successfully watched the ad, a verification request will be sent to the verification interface you configured in the CSJ platform, and the developer will determine whether the user will be rewarded for this viewing.
Key Note: The CSJ server only transmits the verification request transparently, and does not add verification logic in the intermediate process. In order to protect the interests of developers and user experience, developers can add their own verification logic in the verification process.

Callback method description

The CSJ server will request the callback link of the third-party service by GET method, and splicing the following parameters to return:
user_id=%s&trans_id=%s&reward_name=%s&reward_amount=%d&extra=%s&sign=%s

Field name Field definition Field type Remarks
sign Signature string Signature
user_id tagid string Call SDK to pass through
trans_id Transaction string The unique transaction ID that completed the watch
reward_amount rewardAmount int The value configured when the media platform creates the code bit
reward_name rewardName sting The name configured when the media platform created the code bit
extra Extra string Call the SDK to pass in and pass it through, or empty if not needed

Signature generation method

appSecurityKey: The key you obtained from the newly created reward video code bit on the CSJ media platform
transId:Transaction id

sign = sha256(appSecurityKey:transId)

Python Example:

import hashlib
if __name__ == "__main__":
    trans_id = "6FEB23ACB0374985A2A52D282EDD5361u6643"
    app_security_key = "7ca31ab0a59d69a42dd8abc7cf2d8fbd"
    check_sign_raw = "%s:%s" % (app_security_key, trans_id)
    sign = hashlib.sha256(check_sign_raw).hexdigest()

Conventional return parameters

Field name Field definition Field type Remarks
isValid Check result bool Judgment result, whether to issue rewards

Note:
According to SDK requirements, the callback url that needs to be judged by the server is a get request. The default return is a json string {"isValid": true}

Example:

{
    "isValid": true
}

Destroy the ad object

//在Activity的onDestroy方法中清空广告对象
 @Override
    protected void onDestroy() {
        super.onDestroy();
        if (mttRewardVideoAd != null) {
            mttRewardVideoAd = null ;
        }
}

Reference Demo

For rewarded video ads, please refer to RewardVideoActivity in Demo

Did the content solve your problem?
Contact us