Menu

Interstitial 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 onInterstitialAdLoaded, 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 onInterstitialAdVideoStart 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
ATInterstitial mInterstitialAd = new ATInterstitial(activity, "your placement id");
//Set the ad listener
mInterstitialAd.setAdListener(new ATInterstitialListener() {
    @Override
    public void onInterstitialAdLoaded() {
        // Load-success callback
        // Reset the retry load count
        retryAttempt = 0;
    }
        
    @Override
    public void onInterstitialAdLoadFail(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 number of retries (3 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() {
                mInterstitialAd.load();
            }
        }, delayMillis);
    }

    @Override
    public void onInterstitialAdShow(ATAdInfo adInfo) {
        //It is recommended to call load in this callback to load the ad for the next display (no need to call isAdReady())
        mInterstitialAd.load();
    }

    @Override
    public void onInterstitialAdVideoStart(ATAdInfo adInfo) {}
        
    @Override
    public void onInterstitialAdVideoEnd(ATAdInfo adInfo) {}
        
    @Override
    public void onInterstitialAdVideoError(AdError adError, ATAdInfo adInfo) {
        // Show-failure callback
        mInterstitialAd.load();
    }
        
    @Override
    public void onInterstitialAdClose(ATAdInfo adInfo) {
        // Ad-close callback
        mInterstitialAd.load();
    }
        
    @Override
    public void onInterstitialAdClicked(ATAdInfo adInfo) {}
});
mInterstitialAd.load();
java Copy
TUInterstitial mInterstitialAd = new TUInterstitial(activity, "your placement id");
//Set the ad listener
mInterstitialAd.setAdListener(new TUInterstitialListener() {
    @Override
    public void onInterstitialAdLoaded() {
        // Load-success callback
        // Reset the retry load count
        retryAttempt = 0;
    }
        
    @Override
    public void onInterstitialAdLoadFail(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 number of retries (3 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() {
                mInterstitialAd.load();
            }
        }, delayMillis);
    }

    @Override
    public void onInterstitialAdShow(TUAdInfo adInfo) {
        //It is recommended to call load in this callback to load the ad for the next display (no need to call isAdReady())
        mInterstitialAd.load();
    }

    @Override
    public void onInterstitialAdVideoStart(TUAdInfo adInfo) {}
        
    @Override
    public void onInterstitialAdVideoEnd(TUAdInfo adInfo) {}
        
    @Override
    public void onInterstitialAdVideoError(AdError adError, TUAdInfo adInfo) {
        // Show-failure callback
        mInterstitialAd.load();
    }
        
    @Override
    public void onInterstitialAdClose(TUAdInfo adInfo) {
        // Ad-close callback
        mInterstitialAd.load();
    }
        
    @Override
    public void onInterstitialAdClicked(TUAdInfo adInfo) {}
});
mInterstitialAd.load();

💡Tips:

● Before displaying the ad, it is recommended to first call mInterstitialAd.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 (mInterstitialAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mInterstitialAd.show(activity,showConfig);
} else {
   mInterstitialAd.load();
}
java Copy
if (mInterstitialAd.isAdReady()) {
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mInterstitialAd.show(activity,showConfig);
} else {
   mInterstitialAd.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
ATInterstitial.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
mInterstitialAd.entryAdScenario("your scenario id");
if (mInterstitialAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mInterstitialAd.show(activity,showConfig);
} else {
   mInterstitialAd.load();
}
java Copy
TUInterstitial.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
mInterstitialAd.entryAdScenario("your scenario id");
if (mInterstitialAd.isAdReady()) {
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mInterstitialAd.show(activity,showConfig);
} else {
   mInterstitialAd.load();
}

5. API Description

● ATInterstitial

Interstitial ad operation class, responsible for ad loading, listening, display, etc.

Method Description
ATInterstitial(Context context, String placmentId) Splash ad initialization method
context: Context, recommended to pass in an Activity
placmentId: Interstitial-style Ad Placement, obtained by creating an Interstitial Ad Placement in the TopOn backend
void setLocalExtra(Map map) Set custom information before loading the ad or when displaying it
void setAdListener(ATInterstitialListener listener) Set the Ad Placement level ad listener callback
listener: Ad Placement event callback interface class
void load() Initiate ad loading
void load(Context context) Initiate ad loading; developers can call this method to load the ad using a specified Context
boolean isAdReady() Check whether the Ad Placement has an ad available to display. Return value:
true = an ad is available to display
false = no ad is available to display
void show(Activity activity, ATShowConfig showConfig) Display the ad, passing in custom parameters for display and the Ad Scenario
Parameter 2: display configuration, including custom parameters and the ad scenario
void entryAdScenario(String placementId, String scenarioId) Reports the cache status statistics of the current Ad Placement when entering a business scenario. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null will count toward the default scenario)
void entryAdScenario(String scenarioId) (6.5.80 and above) Reports the cache status statistics of the current Ad Placement when entering a business scenario. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null will count toward the default scenario)

● ATInterstitialListener

Ad Placement level Ad Event Callbacks

Method Description
void onInterstitialAdLoaded() Ad load-success callback
void onInterstitialAdLoadFail(AdError error) Ad load-failure callback. You can get the full error information via AdError.getFullErrorInfo()
error: error information
Note: Do not call the ad load method in this callback to retry; otherwise it will cause many useless requests and may cause the app to freeze
void onInterstitialAdShow(ATAdInfo adInfo) Ad display callback
adInfo: ad information object
void onInterstitialAdVideoStart(ATAdInfo adInfo) Video ad playback start callback
adInfo: ad information object
void onInterstitialAdVideoEnd(ATAdInfo adInfo) Video ad playback end callback
adInfo: ad information object
void onInterstitialAdVideoError(AdError errorCode) Video ad playback failure callback
errorCode: error information
void onInterstitialAdClose(ATAdInfo adInfo) Ad-close callback. It is recommended to call load in this callback to load the ad for the next display
adInfo: ad information object
void onInterstitialAdClicked(ATAdInfo adInfo) Ad click callback
adInfo: ad information object

● TUInterstitial

Interstitial ad operation class, responsible for ad loading, listening, display, etc.

Method Description
TUInterstitial(Context context, String placmentId) Splash ad initialization method
context: Context, recommended to pass in an Activity
placmentId: Interstitial-style Ad Placement, obtained by creating an Interstitial Ad Placement in the TopOn backend
void setLocalExtra(Map map) Set custom information before loading the ad or when displaying it
void setAdListener(TUInterstitialListener listener) Set the Ad Placement level ad listener callback listener: Ad Placement event callback interface class
void load() Initiate ad loading
void load(Context context) Initiate ad loading; developers can call this method to load the ad using a specified Context
boolean isAdReady() Check whether the Ad Placement has an ad available to display. Return value:
true = an ad is available to display
false = no ad is available to display
void show(Activity activity, TUShowConfig showConfig) Display the ad, passing in custom parameters for display and the Ad Scenario
Parameter 2: display configuration, including custom parameters and the ad scenario
void entryAdScenario(String placementId, String scenarioId) Reports the cache status statistics of the current Ad Placement when entering a business scenario. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null will count toward the default scenario)

● TUInterstitialListener

Ad Placement level Ad Event Callbacks

Method Description
void onInterstitialAdLoaded() Ad load-success callback
void onInterstitialAdLoadFail(AdError error) Ad load-failure callback. You can get the full error information via AdError.getFullErrorInfo()
error: error information
Note: Do not call the ad load method in this callback to retry; otherwise it will cause many useless requests and may cause the app to freeze
void onInterstitialAdShow(TUAdInfo adInfo) Ad display callback
adInfo: ad information object
void onInterstitialAdVideoStart(TUAdInfo adInfo) Video ad playback start callback
adInfo: ad information object
void onInterstitialAdVideoEnd(TUAdInfo aInfo) Video ad playback end callback
adInfo: ad information object
void onInterstitialAdVideoError(AdError errorCode) Video ad playback failure callback
errorCode: error information
void onInterstitialAdClose(TUAdInfo adInfo) Ad-close callback. It is recommended to call load in this callback to load the ad for the next display
adInfo: ad information object
void onInterstitialAdClicked(TUAdInfo adInfo) Ad click callback
adInfo: ad information object

6. Advanced Settings

Auto Load: A one-stop request management solution launched by TopOn that can intelligently determine the preloading and caching timing of the next ad at multiple nodes based on the user's usage status and ad consumption progress.

Custom Interstitial Ad: Configure native ads on an Interstitial ad placement.

Preset Policy: Improve the ad loading performance of the first cold start by configuring a preset policy.


7. Integration Reference

Sample Code: InterstitialAdActivity.java in the Demo

Previous
Rewarded Ads
Next
Customized Interstitial Ad
Last modified: 2026-07-08Powered by