Menu

Rewarded Ads

1. Integration Suggestions

  • Before displaying, check whether isAdReady is ready. Display the ad by calling show when ready. If not ready, initiate an ad load and wait for the ad to load successfully. If you need to display the ad in the load success callback onRewardedVideoAdLoaded, you must first check that the current app is in the foreground before executing the display method; otherwise, it may cause the ad to be displayed outside the app or fail to display properly.

1.2 Ad Preloading

  • Please call the load method in advance to request an ad (e.g., start loading the ad when the app starts) so that the ad can be displayed quickly when needed.
  • After the ad is displayed, in the onRewardedVideoAdPlayStart callback, directly call load for preloading without checking isAdReady (this helps increase the impression volume for higher-priority ad sources).

It is recommended that you call this step in advance to reduce the waiting time caused by the ad loading time for users.

java Copy
ATRewardVideoAd mRewardVideoAd = new ATRewardVideoAd(this, "your placement id");
//Set the ad listener
mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
    @Override
    public void onRewardedVideoAdLoaded() {
        // Load-success callback
        // Reset the retry load count
        retryAttempt = 0;
    }
    
    @Override
    public void onRewardedVideoAdFailed(AdError adError) {
        // Load-failure callback
        // We recommend extending the retry interval exponentially, until reaching the maximum delay (8 seconds in this example) or the maximum retry count (3 times in this example)
        if (retryAttempt >= 3) return;
        retryAttempt++;
        long delayMillis = TimeUnit.SECONDS.toMillis((long) Math.pow(2, Math.min(3, retryAttempt)));
        new Handler().postDelayed(new Runnable() {
            @Override
            public void run() {
                mRewardVideoAd.load();
            }
        }, delayMillis);
    }
    
    @Override
    public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {}
    
    @Override
    public void onRewardedVideoAdPlayEnd(ATAdInfo adInfo) {}
    
    @Override
    public void onRewardedVideoAdPlayFailed(AdError adError, ATAdInfo adInfo) {
        // Show-failure callback
        // pre-load
        mRewardVideoAd.load();
    }
    
    @Override
    public void onRewardedVideoAdClosed(ATAdInfo adInfo) {
        // Ad-close callback
        // pre-load
        mRewardVideoAd.load();
    }
    
    @Override
    public void onReward(ATAdInfo adInfo) {
        //We recommend granting the reward in this callback
    }
    
    @Override
    public void onRewardedVideoAdPlayClicked(ATAdInfo adInfo) {}
});
mRewardVideoAd.load();
java Copy
TURewardVideoAd mRewardVideoAd = new TURewardVideoAd(this, "your placement id");
//Set the ad listener
mRewardVideoAd.setAdListener(new TURewardVideoListener() {
    @Override
    public void onRewardedVideoAdLoaded() {
        // Load-success callback
        // Reset the retry load count
        retryAttempt = 0;
    }
    
    @Override
    public void onRewardedVideoAdFailed(AdError adError) {
        // Load-failure callback
        // We recommend extending the retry interval exponentially, until reaching the maximum delay (8 seconds in this example) or the maximum retry count (3 times in this example)
        if (retryAttempt >= 3) return;
        retryAttempt++;
        long delayMillis = TimeUnit.SECONDS.toMillis((long) Math.pow(2, Math.min(3, retryAttempt)));
        new Handler().postDelayed(new Runnable() {
            @Override
            public void run() {
                mRewardVideoAd.load();
            }
        }, delayMillis);
    }
    
    @Override
    public void onRewardedVideoAdPlayStart(TUAdInfo adInfo) {}
    
    @Override
    public void onRewardedVideoAdPlayEnd(TUAdInfo adInfo) {}
    
    @Override
    public void onRewardedVideoAdPlayFailed(AdError adError, TUAdInfo adInfo) {
        // Show-failure callback
        // pre-load
        mRewardVideoAd.load();
    }
    
    @Override
    public void onRewardedVideoAdClosed(TUAdInfo adInfo) {
        // Ad-close callback
        // pre-load
        mRewardVideoAd.load();
    }
    
    @Override
    public void onReward(TUAdInfo adInfo) {
        //We recommend granting the reward in this callback
    }
    
    @Override
    public void onRewardedVideoAdPlayClicked(TUAdInfo adInfo) {}
});
mRewardVideoAd.load();

💡Tips:

● Before displaying the ad, it is recommended to first call mRewardVideoAd.isAdReady(). If the value is true, display the ad. If the value is false, load in real time and wait for the load to succeed before displaying the ad.

java Copy
if (mRewardVideoAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mRewardVideoAd.show(activity,showConfig);
} else {
   mRewardVideoAd.load();
}
java Copy
if (mRewardVideoAd.isAdReady()) {
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mRewardVideoAd.show(activity,showConfig);
} else {
   mRewardVideoAd.load();
}

4. Ad Scenario Statistics

Scenario Arrival Rate Statistics, presented in the dashboard's Data Reports -> Funnel Analysis Report -> Ad Scenario Arrival. It is recommended to call it in the correct place.

  1. First, call entryAdScenario()
  2. Then call isAdReady()
  3. Finally, call show() to display
Method Description
void entryAdScenario(String placementId, String scenarioId) Statistics of the current placement's cache status upon entering a business scenario. For specific usage, see Ad Scenario. placementId: Placement ID. scenarioId: Ad scenario ID (not required; passing null will count it under the default scenario).
void entryAdScenario(String scenarioId) (v6.5.80 and above) Statistics of the current placement's cache status upon entering a business scenario. For specific usage, see Ad Scenario. scenarioId: Ad scenario ID (not required; passing null will count it under the default scenario).
java Copy
ATRewardVideoAd.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
mRewardVideoAd.entryAdScenario( "your scenario id");
if (mRewardVideoAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mRewardVideoAd.show(activity,showConfig);
} else {
   mRewardVideoAd.load();
}
java Copy
TURewardVideoAd.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
mRewardVideoAd.entryAdScenario("your scenario id");
if (mRewardVideoAd.isAdReady()) {
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mRewardVideoAd.show(activity,showConfig);
} else {
   mRewardVideoAd.load();
}

5. Set Custom Parameters

  • Pass custom parameters before loading or during display, which can be retrieved in the callback info AdInfo.
  • The custom parameters passed during display are independent of those passed during loading. At the same time, the TopOn server-side reward callback also supports returning the custom parameters passed during display.

⚠️Tips

The passed custom parameters can be obtained in the onRewardedVideoAdLoaded() callback via ATAdInfo#getLocalExtra(). Be sure to keep the KEY consistent.

⚠️Tips

The custom parameters passed in can be retrieved through ATAdInfo#getLocalExtra() in the onRewardedVideoAdLoaded() callback. Note to keep the KEY consistent

java Copy
ATRewardVideoAd mRewardVideoAd = new ATRewardVideoAd(this, "your placement id");
String userdata = "test_userdata_001";
Map<String, Object> localMap = new HashMap<>();
localMap.put(ATAdConst.KEY.USER_CUSTOM_DATA, userdata);
//Set reward-related parameters before loading the ad
mRewardVideoAd.setLocalExtra(localExtraMap);
mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
    ...
    @Override
    public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
        //Retrieve the reward-related parameters set before loading the ad in this callback
        getUserCustomDataOnLoaded(adInfo);
    }
    ...
});

mRewardVideoAd.load();

private void getUserCustomDataOnLoaded(ATAdInfo adInfo) {
    if (adInfo != null) {
        Map localExtraMap = adInfo.getLocalExtra();
        if (localExtraMap != null) {
            //Retrieve the custom parameter through the key (consistent with the key set before loading the ad)
            Object userCustomData = localExtraMap.get(ATAdConst.KEY.USER_CUSTOM_DATA);
            //Use the custom parameter userCustomData for your required logic
            //...
        }
    }
}

⚠️Tips

The custom parameters passed in can be retrieved through TUAdInfo#getLocalExtra() in the onRewardedVideoAdLoaded() callback. Note to keep the KEY consistent

java Copy
TURewardVideoAd mRewardVideoAd = new TURewardVideoAd(this, "your placement id");
String userdata = "test_userdata_001";
Map<String, Object> localMap = new HashMap<>();
localMap.put(TUAdConst.KEY.USER_CUSTOM_DATA, userdata);
//Set reward-related parameters before loading the ad
mRewardVideoAd.setLocalExtra(localExtraMap);
mRewardVideoAd.setAdListener(new TURewardVideoListener() {
    ...
    @Override
    public void onRewardedVideoAdPlayStart(TUAdInfo adInfo) {
        //Retrieve the reward-related parameters set before loading the ad in this callback
        getUserCustomDataOnLoaded(adInfo);
    }
    ...
});

mRewardVideoAd.load();

private void getUserCustomDataOnLoaded(TUAdInfo adInfo) {
    if (adInfo != null) {
        Map localExtraMap = adInfo.getLocalExtra();
        if (localExtraMap != null) {
            //Retrieve the custom parameter through the key (consistent with the key set before loading the ad)
            Object userCustomData = localExtraMap.get(TUAdConst.KEY.USER_CUSTOM_DATA);
            //Use the custom parameter userCustomData for your required logic
            //...
        }
    }
}

5.2 Pass Custom Parameters When Displaying

⚠️Tips

The passed custom parameters can be obtained in the onRewardedVideoAdPlayStart() callback via ATAdInfo#getShowCustomExt().

⚠️Tips

The custom parameters passed in can be retrieved through ATAdInfo#getShowCustomExt() in the onRewardedVideoAdPlayStart() callback

java Copy
ATRewardVideoAd mRewardVideoAd = new ATRewardVideoAd(this, "your placement id");
mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
    ...
    @Override
    public void onRewardedVideoAdLoaded() {
        ATShowConfig showConfig = new ATShowConfig.Builder()
                .showCustomExt("custom_show_data")
                .build();
        mRewardVideoAd.show(activity, showConfig);
    }
    
    @Override
    public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
        if (adInfo != null) {
            String showCustomExt = adInfo.getShowCustomExt();
            //showCustomExt is the custom_show_data above
        }
    }
    ...
});
mRewardVideoAd.load();

⚠️Tips

The custom parameters passed in can be retrieved through TUAdInfo#getShowCustomExt() in the onRewardedVideoAdPlayStart() callback

java Copy
TURewardVideoAd mRewardVideoAd = new TURewardVideoAd(this, "your placement id");
mRewardVideoAd.setAdListener(new TURewardVideoListener() {
    ...
    @Override
    public void onRewardedVideoAdLoaded() {
        TUShowConfig showConfig = new TUShowConfig.Builder()
                .showCustomExt("custom_show_data")
                .build();
        mRewardVideoAd.show(activity,showConfig);
    }
    
    @Override
    public void onRewardedVideoAdPlayStart(TUAdInfo adInfo) {
        if (adInfo != null) {
            String showCustomExt = adInfo.getShowCustomExt();
            //showCustomExt is the custom_show_data above
        }
    }
    ...
});
mRewardVideoAd.load();

6. API Description

● ATRewardVideoAd

The operation class for Rewarded Video ads, responsible for ad loading, listening, display, etc.

Method Description
ATRewardVideoAd(Context context, String placementID) Initialization method for RewardedVideo ads.
context: If the following platforms are integrated: IronSource, Kidoz, Maio, Tapjoy, the context must be an Activity.
placementID: Rewarded Video-type placement, obtained by creating a Rewarded Video Placement in the TopOn dashboard.
void setLocalExtra(Map map) Set custom information before loading the ad or during display.
void setAdListener(ATRewardVideoListener listener) Set the placement-level ad listener callback. listener: The interface class for placement event callbacks.
void load() Initiate an ad load.
void load(Context context) Initiate an ad load. Developers can use this method to load the ad with a specified Context.
boolean isAdReady() Determine whether a displayable ad exists for the current placement. Return value:
true = a displayable ad exists
false = no displayable ad exists
show(Activity activity) Display the ad.
void show(Activity activity, ATShowConfig showConfig) Display the ad, passing custom parameters and the Ad Scenario during display.
showConfig: Display ad configuration, including custom parameters and the ad scenario.
void entryAdScenario(String placementId, String scenarioId) Statistics of the current placement's cache status upon entering a business scenario. For specific usage, see Ad Scenario.
placementId: Placement ID.
scenarioId: Ad scenario ID (not required; passing null will count it under the default scenario).
void entryAdScenario(String scenarioId) (v6.5.80 and above) Statistics of the current placement's cache status upon entering a business scenario. For specific usage, see Ad Scenario.
scenarioId: Ad scenario ID (not required; passing null will count it under the default scenario).

● ATRewardVideoListener

Placement-level ad event callbacks.

Method Description
void onRewardedVideoAdLoaded() Callback for successful ad loading.
void onRewardedVideoAdFailed(AdError error) Callback for ad loading failure. You can obtain all error information via AdError.getFullErrorInfo().
error: Error information.
Note: Do not execute the ad loading method for retries in this callback; otherwise, it will cause many unnecessary requests and may cause the app to freeze.
void onRewardedVideoAdPlayStart(ATAdInfo adInfo) Callback for when the ad starts playing (i.e., Rewarded Video impression callback).
adInfo: Ad information object.
void onRewardedVideoAdPlayEnd(ATAdInfo adInfo) Callback for when the ad finishes playing.
adInfo: Ad information object.
void onRewardedVideoAdPlayFailed(AdError errorCode, ATAdInfo adInfo) Callback for when the ad fails to play.
errorCode: Error information.
adInfo: Ad information object.
void onReward(ATAdInfo adInfo) This callback is triggered when a reward is granted. It is recommended that you grant the reward in this callback, which is generally called before onRewardedVideoAdClosed.
adInfo: Ad information object.
void onRewardedVideoAdClosed(ATAdInfo adInfo) Callback for when the ad is dismissed. It is recommended to call load in this callback to load the ad for the next display.
adInfo: Ad information object.
void onRewardedVideoAdPlayClicked(ATAdInfo adInfo) Callback for when the ad is clicked.
atAdInfo: Ad information object.
Previous
AD Formats
Next
Interstitial Ads
Last modified: 2026-07-08Powered by