Menu

Interstitial ad

1. Interstitial Ad Introduction

Interstitial ads aggregate picture interstitial ads and video interstitial ads from other third-party ad networks. Both ad types can be loaded and displayed using the ATAdManager API. Currently, two integration methods are supported, as described below:

Mode (choose one) Description
Manual Request Mode You call ad loading through the API at an appropriate time at your own discretion. Refer to the integration suggestions below in the document for details.
Auto Load Mode A one-stop request management solution launched by TopOn, which can automatically determine the preloading and caching timing of the next ad based on the user's usage status and ad consumption progress, achieving better loading performance. See: Interstitial Ad Auto Load Mode for details.

2. Integration Process Suggestions

  1. When the app starts, execute ad loading via ATInterstitialAd#loadInterstitialAd.
  2. At the position where you need to display an ad, check whether it can be shown via ATInterstitialAd#hasInterstitialAdReady.

false: Re-execute ATInterstitialAd#loadInterstitialAd to load the ad.

true: Execute ATInterstitialAd#showInterstitialAd to display the ad, and then execute ATInterstitialAd#loadInterstitialAd again in the onInterstitialAdClose callback to preload the next ad. (In the onInterstitialAdClose callback, you can directly call loadInterstitialAd without needing to go through the hasInterstitialAdReady check. This helps increase the impression volume for higher-priority ad sources.)

  1. Ad Preloading:

After the interstitial ad is displayed, in the onInterstitialAdShow (v5.8.10 and later) or onInterstitialAdClose (prior to v5.8.10) callback, directly call ATInterstitialAd#loadInterstitialAd for preloading without the ATInterstitialAd#hasInterstitialAdReady check (this helps increase the impression volume for higher-priority ad sources).

You can refer to the auto request ad feature and enable auto request ad (if the above post-display preload has already been implemented, this does not need to be enabled).

  1. If you need to use ad scenarios to differentiate data for different business scenarios, refer to the sample code for details.

3. API Description

ATInterstitialAd:

API Parameters Description
loadInterstitialAd string placementid, Dictionary extra Load an ad
setListener ATInterstitialAdListener listener Set the listener callback interface (deprecated after version 5.9.51)
hasInterstitialAdReady string placementid Check if there is an ad cache
checkAdStatus string placementid (Added in v5.7.03) Get the status of the current placement (JSON string): 1. isLoading: whether it is currently loading 2. isReady: whether there is an ad cache (same functionality as hasInterstitialAdReady) 3. AdInfo: information of the highest-priority cached ad (refer to ATCallbackInfo Description)
getValidAdCaches string placementid (Added in v5.7.54) Get all successfully loaded ad cache information (JSON string) (refer to ATCallbackInfo Description)
showInterstitialAd string placementid, Dictionary extra Show an ad
entryScenarioWithPlacementID string placementId, string scenarioID Set entry into a displayable ad scenario

Use the following code to load an interstitial ad:

java Copy 
public void loadInterstitialAd() 
{

    ATInterstitialAd.Instance.client.onAdLoadEvent += onAdLoad; 
    ATInterstitialAd.Instance.client.onAdLoadFailureEvent += onAdLoadFail;
    ATInterstitialAd.Instance.client.onAdShowEvent += onShow;
    ATInterstitialAd.Instance.client.onAdClickEvent += onAdClick;
    ATInterstitialAd.Instance.client.onAdCloseEvent += onAdClose;
    ATInterstitialAd.Instance.client.onAdShowFailureEvent += onAdShowFail;        
    ATInterstitialAd.Instance.client.onAdVideoStartEvent  += startVideoPlayback;
    ATInterstitialAd.Instance.client.onAdVideoEndEvent  += endVideoPlayback;
    ATInterstitialAd.Instance.client.onAdVideoFailureEvent  += failVideoPlayback;

    Dictionary<string> jsonmap = new Dictionary<string>();

    ATInterstitialAd.Instance.loadInterstitialAd(mPlacementId_interstitial_all, jsonmap);
}</string></string>

Note: Please refer to the following section to learn how to receive notifications about interstitial ad events (load success/failure, display, click, video start/end).

5. Check if There Is an Ad Cache

java Copy 
ATInterstitialAd.Instance.hasInterstitialAdReady(mPlacementId_interstitial_all);

Like Rewarded Video, to show an interstitial ad, simply call the show API and pass the placement ID as a parameter:

java Copy 
public void showInterstitialAd() 
{
    ATInterstitialAd.Instance.showInterstitialAd(mPlacementId_interstitial_all);
}

When using the scenario feature:

java Copy 
public void showInterstitialAd()
{
    Dictionary<string string=""> jsonmap = new Dictionary<string string="">();
    jsonmap.Add(AnyThinkAds.Api.ATConst.SCENARIO, showingScenarioID);
    ATInterstitialAd.Instance.showInterstitialAd(mPlacementId_interstitial_all, jsonmap);
}</string></string>

7. Implement the Interstitial Ad Event Listener

For callback information details, please see: Callback Information Description

Use the following code to implement multiple listeners:

java Copy 
        // Ad loading succeeded
        ATInterstitialAd.Instance.client.onAdLoadEvent += onAdLoad; 
        // Ad loading failed
        ATInterstitialAd.Instance.client.onAdLoadFailureEvent += onAdLoadFail;
        // Ad displayed (this callback can be relied on for impression statistics)
        ATInterstitialAd.Instance.client.onAdShowEvent += onShow;
        // Ad clicked
        ATInterstitialAd.Instance.client.onAdClickEvent += onAdClick;
        // Ad dismissed
        ATInterstitialAd.Instance.client.onAdCloseEvent += onAdClose;
        // Ad display failed
        ATInterstitialAd.Instance.client.onAdShowFailureEvent += onAdShowFail;        
        // Video ad playback started
        ATInterstitialAd.Instance.client.onAdVideoStartEvent  += startVideoPlayback;
        // Video ad playback ended
        ATInterstitialAd.Instance.client.onAdVideoEndEvent  += endVideoPlayback;
        // Video ad playback failed
        ATInterstitialAd.Instance.client.onAdVideoFailureEvent  += failVideoPlayback;

The method parameter definitions are as follows in the code (Note: The method name can follow the code below or be a custom method name, but the parameters must be consistent.):

java Copy 
    // sender is the ad type object, erg is the returned information
    // Ad clicked
    public void onAdClick(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdClick :" + erg.placementId);
    }
    // Ad dismissed
    public void onAdClose(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdClose :" + erg.placementId);
    }
    // Ad video playback ended (some ad networks have this callback)
    public void endVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdEndPlayingVideo :" + erg.placementId);
    }
    // Ad video playback failed (some ad networks have this callback)
    public void failVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdFailedToPlayVideo :" + erg.placementId + "--code:" + erg.code + "--msg:" + erg.message);
    }
    // Ad loading succeeded
    public void onAdLoad(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdLoad :" + erg.placementId);
    }
    // Ad loading failed
    public void onAdLoadFail(object sender,ATAdErrorEventArgs erg )
    {
        Debug.Log("Developer callback onInterstitialAdLoadFail :" + erg.placementId + "--erg.code:" + code + "--msg:" + erg.message);
    }
    // Ad display succeeded
    public void onShow(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdShow :" +erg. placementId);
    }
    // Ad video playback started (some platforms have this callback)
    public void startVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdStartPlayingVideo :" + erg.placementId);
    }
    // Ad display failed
    public void failVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdFailedToShow :" + erg.placementId);
    }
Previous
Fully automatic loading of incentive videos
Next
Fully automatic loading of interstitial ads
Last modified: 2026-07-03Powered by