Interstitial ad

1. Interstitial Ad Introduction

Interstitial ads aggregate image interstitial ads and video interstitial ads from other third-party ad platforms. Both ad types can be loaded and displayed using the ATAdManager API. Two integration modes are currently supported, as described below:

Mode (Choose One)	Description
Manual Request Mode	You call the ad load API yourself at the appropriate timing. See the integration suggestions below for details.
Auto Load Mode	A one-stop request maintenance solution launched by Taku that automatically determines the preloading and caching timing for the next ad based on user usage status and ad consumption progress, achieving better loading results. See: Interstitial Ad Auto Load Mode for details.

2. Integration Process Suggestions

Call ATInterstitialAd#loadInterstitialAd to load an ad when the app starts
Use ATInterstitialAd#hasInterstitialAdReady to check if an ad can be displayed at the location where you want to show it

false: Call ATInterstitialAd#loadInterstitialAd again to load an ad

true: Call ATInterstitialAd#showInterstitialAd to display the ad. In the onInterstitialAdClose callback, call ATInterstitialAd#loadInterstitialAd again to preload the next ad (in the onInterstitialAdClose callback, you can call loadInterstitialAd directly without checking hasInterstitialAdReady first, which helps increase the impression volume of higher-priority Ad Sources.)

Ad Preloading:

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

You can refer to Auto Request Ads and enable Auto Request Ads (not needed if the above post-display preloading is already implemented).

If you need to use ad scenarios to distinguish data for different business scenarios, see the sample code for details.

3. API Description

ATInterstitialAd:

API	Parameters	Description
loadInterstitialAd	string placementid, Dictionary	Load an ad
setListener	ATInterstitialAdListener listener	Set the listener callback interface. (Deprecated after version 5.9.51) For how to set listeners, see: Interstitial Ad Event Settings
hasInterstitialAdReady	string placementid	Check if there is a cached ad
checkAdStatus	string placementid	(Added in v5.7.03) Get the current ad placement status (JSON string): 1. isLoading: Whether it is loading 2. isReady: Whether there is a cached ad (same as hasInterstitialAdReady) 3. AdInfo: The highest-priority cached ad info (see ATCallbackInfo Description)
getValidAdCaches	string placementid	(Added in v5.7.54) Get all successfully loaded cached ad info (JSON string) (see ATCallbackInfo Description)
showInterstitialAd	string placementid, Dictionary	Display an ad
entryScenarioWithPlacementID	string placementId, string scenarioID	Set entry into a displayable ad scenario

4. Load Interstitial Ad

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 jsonmap = new Dictionary();

    ATInterstitialAd.Instance.loadInterstitialAd(mPlacementId_interstitial_all, jsonmap);
}

Note: See below for how to get notified about interstitial ad events (load success/failure, impression, click, video start/end).

5. Check If There Is a Cached Ad

java Copy

ATInterstitialAd.Instance.hasInterstitialAdReady(mPlacementId_interstitial_all);

6. Display Interstitial Ad

Same as rewarded video, to display an interstitial ad, simply call the show API and pass the ad 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 jsonmap = new Dictionary();
    jsonmap.Add(AnyThinkAds.Api.ATConst.SCENARIO, showingScenarioID);
    ATInterstitialAd.Instance.showInterstitialAd(mPlacementId_interstitial_all, jsonmap);
}

7. Implement Interstitial Ad Event Listeners (Note: Only supported on V5.951 and above)

For callback info details, see: Callback Info Description

Use the following code to implement multiple listeners:

java Copy

        // Ad loaded successfully
        ATInterstitialAd.Instance.client.onAdLoadEvent += onAdLoad; 
        // Ad load failed
        ATInterstitialAd.Instance.client.onAdLoadFailureEvent += onAdLoadFail;
        // Ad displayed (can rely on this callback for impression statistics)
        ATInterstitialAd.Instance.client.onAdShowEvent += onShow;
        // Ad clicked
        ATInterstitialAd.Instance.client.onAdClickEvent += onAdClick;
        // Ad closed
        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;

Advanced listener settings:

java Copy

        // Ad Source initiated request
        ATInterstitialAd.Instance.client.onAdSourceAttemptEvent += startLoadingADSource;
        // Ad Source loaded successfully
        ATInterstitialAd.Instance.client.onAdSourceFilledEvent += finishLoadingADSource;
        // Ad Source load failed
        ATInterstitialAd.Instance.client.onAdSourceLoadFailureEvent += failToLoadADSource;
        // Ad Source Bidding started
        ATInterstitialAd.Instance.client.onAdSourceBiddingAttemptEvent += startBiddingADSource;
        // Ad Source Bidding succeeded
        ATInterstitialAd.Instance.client.onAdSourceBiddingFilledEvent += finishBiddingADSource;
        // Ad Source Bidding failed
        ATInterstitialAd.Instance.client.onAdSourceBiddingFailureEvent += failBiddingADSource;

The method definition parameters are as follows (Note: You can refer to the code below for method names or use custom method names, but the parameters must be consistent):

java Copy

    //sender is the ad type object, erg is the returned info
    // Ad clicked
    public void onAdClick(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdClick :" + erg.placementId);
    }
    // Ad closed
    public void onAdClose(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdClose :" + erg.placementId);
    }
    // Video ad playback ended, some ad platforms have this callback
    public void endVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdEndPlayingVideo :" + erg.placementId);
    }
    // Video ad playback failed, some ad platforms have this callback
    public void failVideoPlayback(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdFailedToPlayVideo :" + erg.placementId + "--code:" + erg.code + "--msg:" + erg.message);
    }
    // Ad loaded successfully
    public void onAdLoad(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdLoad :" + erg.placementId);
    }
    // Ad load failed
    public void onAdLoadFail(object sender,ATAdErrorEventArgs erg )
    {
        Debug.Log("Developer callback onInterstitialAdLoadFail :" + erg.placementId + "--erg.code:" + code + "--msg:" + erg.message);
    }
    // Ad displayed successfully
    public void onShow(object sender,ATAdEventArgs erg)
    {
        Debug.Log("Developer callback onInterstitialAdShow :" +erg. placementId);
    }
    // Video ad playback started, some ad 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);
    }

      // v5.8.10 added Ad Source-level callbacks
      // Ad Source started loading
    public void startLoadingADSource(object sender,ATAdEventArgs erg){
        Debug.Log("Developer startLoadingADSource------");
    }
      // Ad Source loading completed
        public void finishLoadingADSource(object sender,ATAdEventArgs erg){
        Debug.Log("Developer finishLoadingADSource------");
    }
      // Ad Source failed
        public void failToLoadADSource(object sender,ATAdEventArgs erg){
        Debug.Log("Developer failToLoadADSource------");
    }
      // Ad Source started bidding
        public void startBiddingADSource(object sender,ATAdEventArgs erg){
               Debug.Log("Developer startBiddingADSource------");
    }
      // Ad Source bidding succeeded
        public void finishBiddingADSource(object sender,ATAdEventArgs erg){
        Debug.Log("Developer finishBiddingADSource------");
    }
      // Ad Source bidding failed
        public void failBiddingADSource(object sender,ATAdEventArgs erg){
        Debug.Log("Developer failBiddingADSource------");
    }

8. Legacy Interstitial Listener Implementation (Note: Only for use below V5.9.51, deprecated in new versions)

You can implement a class that implements the ATInterstitialAdListener interface to get notified about interstitial ad events: (Note: For Android, all callback methods are not on the Unity main thread)

java Copy

class InterstitalCallback : ATInterstitialAdListener
{
    // Ad clicked
    public void onInterstitialAdClick(string placementId, ATCallbackInfo callbackInfo)
    {
        Debug.Log("Developer callback onInterstitialAdClick :" + placementId);
    }
    // Ad closed
    public void onInterstitialAdClose(string placementId, ATCallbackInfo callbackInfo)
    {
        Debug.Log("Developer callback onInterstitialAdClose :" + placementId);
    }
    // Video ad playback ended, some ad platforms have this callback
    public void onInterstitialAdEndPlayingVideo(string placementId, ATCallbackInfo callbackInfo)
    {
        Debug.Log("Developer callback onInterstitialAdEndPlayingVideo :" + placementId);
    }
    // Video ad playback failed, some ad platforms have this callback
    public void onInterstitialAdFailedToPlayVideo(string placementId, string code, string message)
    {
        Debug.Log("Developer callback onInterstitialAdFailedToPlayVideo :" + placementId + "--code:" + code + "--msg:" + message);
    }
    // Ad loaded successfully
    public void onInterstitialAdLoad(string placementId)
    {
        Debug.Log("Developer callback onInterstitialAdLoad :" + placementId);
    }
    // Ad load failed
    public void onInterstitialAdLoadFail(string placementId, string code, string message)
    {
        Debug.Log("Developer callback onInterstitialAdLoadFail :" + placementId + "--code:" + code + "--msg:" + message);
    }
    // Ad displayed successfully
    public void onInterstitialAdShow(string placementId, ATCallbackInfo callbackInfo)
    {
        Debug.Log("Developer callback onInterstitialAdShow :" + placementId);
    }
    // Video ad playback started, some ad platforms have this callback
    public void onInterstitialAdStartPlayingVideo(string placementId, ATCallbackInfo callbackInfo)
    {
        Debug.Log("Developer callback onInterstitialAdStartPlayingVideo :" + placementId);
    }
    // Ad display failed
    public void onInterstitialAdFailedToShow(string placementId)
    {
        Debug.Log("Developer callback onInterstitialAdFailedToShow :" + placementId);
    }

      // v5.8.10 added Ad Source-level callbacks
      // Ad Source started loading
    public void startLoadingADSource(string placementId, ATCallbackInfo callbackInfo){
        Debug.Log("Developer startLoadingADSource------");
    }
      // Ad Source loading completed
        public void finishLoadingADSource(string placementId, ATCallbackInfo callbackInfo){
        Debug.Log("Developer finishLoadingADSource------");
    }
      // Ad Source failed
        public void failToLoadADSource(string placementId,ATCallbackInfo callbackInfo,string code, string message){
        Debug.Log("Developer failToLoadADSource------");
    }
      // Ad Source started bidding
        public void startBiddingADSource(string placementId, ATCallbackInfo callbackInfo){
               Debug.Log("Developer startBiddingADSource------");
    }
      // Ad Source bidding succeeded
        public void finishBiddingADSource(string placementId, ATCallbackInfo callbackInfo){
        Debug.Log("Developer finishBiddingADSource------");
    }
      // Ad Source bidding failed
        public void failBiddingADSource(string placementId,ATCallbackInfo callbackInfo,string code, string message){
        Debug.Log("Developer failBiddingADSource------");
    }
}

Note: The code snippets you see in this section are from the interstitialScenes.cs demo project in our Demo.

Fully automatic loading of incentive videos

Fully automatic loading of interstitial ads

Last modified: 2026-07-02Powered by

Outline