Rewarded Ads

1. Integrate Tips

● Show Ad

• CallisAdReady()before showing Ad. Display the Ad if it returns True. Otherwise, initiate the Ad loading instead and wait until the Ad is loaded successfully.
• If you need to show the ad withinonRewardedVideoAdLoaded, you must first verify that the current application is in the foreground in order to show the ad.

● Preload Ad

• To show Ad instantly,  please load the Ad beforehand. (for example, callload()when application starts. )
• Load the  video in queue by calling load() inonRewardedVideoAdPlayStart()to preload the next while playing the current one. Such will generate more impressions for highly-prioritized Ad resources.

2. Load a Rewarded Ad

💡Please call this function in advance to reduce user waiting time.

ATRewardVideoAd mRewardVideoAd = new ATRewardVideoAd(this, "your placement id");
//set ad listener
mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
    @Override
    public void onRewardedVideoAdLoaded() {}
    
    @Override
    public void onRewardedVideoAdFailed(AdError adError) {
        //Note: Do not call load() here, as it may lead to an ANR error
    }
    
    @Override
    public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
        //It is recommended to call load() here for preloading, to facilitate the display of the next ad.
        mRewardVideoAd.load();
    }
    
    @Override
    public void onRewardedVideoAdPlayEnd(ATAdInfo atAdInfo) {}
    
    @Override
    public void onRewardedVideoAdPlayFailed(AdError adError, ATAdInfo atAdInfo) {}
    
    @Override
    public void onRewardedVideoAdClosed(ATAdInfo atAdInfo) {}
    
    @Override
    public void onReward(ATAdInfo atAdInfo) {
        //It is suggested to issue rewards here.
    }
    
    @Override
    public void onRewardedVideoAdPlayClicked(ATAdInfo atAdInfo) {}
});
mRewardVideoAd.load();

3. Show a Rewarded Ad

💡Tips: 

    ● Before displaying the ad,  callisAdReady(). If the returned value is true, then show the ad; if the value is false, load the ad in real-time and wait for it to be fully loaded before displaying.

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

4. Ad Scenario Statistics

Track the scene arrival rates, which are presented in the TopOn dashboard under Report -> Funnel Report -> Scenario.

• First, call entryAdScenario()
• Then, call isAdReady()
• Finally, call show() to display the ad

ATRewardVideoAd.entryAdScenario("your placement id", "your scenario id");
if (mRewardVideoAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mRewardVideoAd.show(activity，showConfig);
} else {
   mRewardVideoAd.load();
}

5. Set custom data

5.1 Pass in custom data before load()

💡Tips

      The custom data passed in can be retrieved in theonRewardedVideoAdLoaded()callback through ATAdInfo#getLocalExtra(). Be sure to keep the KEY consistent.

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);
mRewardVideoAd.setLocalExtra(localExtraMap);
mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
    ...
    @Override
    public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
        getUserCustomDataOnLoaded(adInfo);
    }
    ...
});

mRewardVideoAd.load();

private void getUserCustomDataOnLoaded(ATAdInfo adInfo) {
    if (adInfo != null) {
        Map localExtraMap = adInfo.getLocalExtra();
        if (localExtraMap != null) {
            // Retrieve custom data using the key (consistent with the key set before ad loading)
            Object userCustomData = localExtraMap.get(ATAdConst.KEY.USER_CUSTOM_DATA);
            ...
        }
    }
}

5.2 Pass in custom data when calling show()

💡Tips

      The custom data passed in can be retrieved in theonRewardedVideoAdPlayStart()callback through ATAdInfo#getShowCustomExt().

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 atAdInfo) {
        if (adInfo != null) {
            String showCustomExt = adInfo.getShowCustomExt();
            ...
        }
    }
    ...
});
mRewardVideoAd.load();

6. Advanced

Fully automatic loading : TopOn has launched a one-stop solution that intelligently determines the timing for preloading and caching the next ad based on the user's usage status and the progress of ad consumption.

Preset strategy : By configuring preset strategies, you can improve the ad loading performance during the app's initial cold start.