Menu

Splash ad

1. Ad Introduction

TopOn Unity Plugin 2.0.0 supports integrating splash ads through the C# API. Splash ads are similar to interstitial ads, but they are typically displayed during a cold start or warm start of the app.

2. Integration Suggestions

  1. Cold Start (when the app process does not exist and the app is launched for the first time)

The preferred approach for handling cold starts is to create a new scene as the launch page. Load the ad in the Start() method of this scene. If the load times out, do not display the ad. Refer to the sample code for details.

After starting the app or game, call ATSplashAd.Instance.loadSplashAd() to load the splash ad.

Defer the preloading logic for other ad formats and other network-consuming requests until after the splash ad is displayed, to reduce splash load timeout occurrences.

If the ad load times out (onAdLoadTimeoutEvent(object sender, ATAdEventArgs erg)), do not continue waiting for the ad to fill and go directly to the main interface. The current splash ad is still loading. If it loads successfully, the onAdLoadEvent callback will be triggered.

When the onAdLoadEvent(object sender, ATAdEventArgs erg) callback is triggered and the load has not timed out (when ATAdEventArgs.isTimeout is false), call ATSplashAd.Instance.showSplashAd() to display the ad.

  1. Warm Start (the app temporarily goes to the background via the home button, and when the app process still exists, it returns to the foreground)

When the app returns to the foreground, call ATSplashAd.Instance.hasSplashAdReady() to check whether there is currently an ad cache. If true, call ATSplashAd.Instance.showSplashAd() to display the ad. If false, call ATSplashAd.Instance.loadSplashAd() to preload the ad.

  1. It is recommended to call ATSplashAd.Instance.entryScenarioWithPlacementID() after entering a displayable ad scenario to track the cache status of the current placement. For specific statistical instructions, see the ad scenario feature for differentiating data across different business scenarios.

  2. Ad Preloading: After the splash ad is displayed, call load in the onAdLoadEvent or onAdCloseEvent callback to preload.

If you need to display a splash ad on warm start, it is recommended that when the app goes to the background, call ATSplashAd.Instance.hasSplashAdReady() to check whether there is currently an ad cache. If true, call ATSplashAd.Instance.showSplashAd() to display the ad. If false, call ATSplashAd.Instance.loadSplashAd() to preload the ad.

  1. Configure a fallback splash ad source in the dashboard to reduce load timeout situations. See Fallback Splash Ad for the configuration method.

  2. In Unity, listen for APP foreground events:

To receive notifications of app foreground events, it is recommended that you listen to the OnApplicationPause event. By overriding the OnApplicationPause method, your app will receive alerts for app launch and foreground events and be able to display ads.

Note:

  1. You must call load to load ads only after the TopOn SDK has been successfully initialized.
  2. Only full-screen splash ads are supported.

3. API Description

ATSplashAd:

API Parameters Description
loadSplashAd string placementId, Dictionary Load an ad
hasSplashAdReady string placementId Check if there is an ad cache
showSplashAd string placementid, Dictionary Display an ad
entryScenarioWithPlacementID string placementId, string scenarioID Set entry into a displayable ad scenario

4. Implement the Ad Event Listener

For callback information details, please see: Callback Information Description

Use the following code to implement multiple listeners:

java Copy 
    var client = ATSplashAd.Instance.client;
    // Ad loading succeeded
    client.onAdLoadEvent += onAdLoad;
    // Ad loading failed
    client.onAdLoadFailureEvent += onAdLoadFailed;
    // Ad load timed out
    client.onAdLoadTimeoutEvent += onAdLoadTimeout;
    // Ad displayed successfully
    client.onAdShowEvent += onAdShow;
    // Ad dismissed
    client.onAdCloseEvent += onAdClose;
    // Ad clicked
    client.onAdClickEvent += onAdClick;

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 
        // Ad loading succeeded
        public void onAdLoad(object sender,ATAdEventArgs erg)
    {
                if (!erg.isTimeout)    // Not a timed-out load
        {
              Debug.Log("Developer onAdLoad------" + erg.placementId);
        }
          else    // Already timed out
        {
              Debug.Log("Developer onAdLoad timeout ------" + erg.placementId);
        }
    }
        // Ad loading failed
        public void onAdLoadFailed(object sender,ATAdEventArgs erg)
    {
          Debug.Log("Developer onAdLoadFailed------" + erg.placementId);
    }
        // Ad load timed out
        public void onAdLoadTimeout(object sender,ATAdEventArgs erg)
    {
          Debug.Log("Developer onAdLoadTimeout------" + erg.placementId);
    }
        // Ad displayed
        public void onAdShow(object sender,ATAdEventArgs erg)
    {
          Debug.Log("Developer onAdShow------" + erg.placementId);
    }
        // Ad dismissed
        public void onAdClose(object sender,ATAdEventArgs erg)
    {
          Debug.Log("Developer onAdClose------" + erg.placementId);
    }
        // Ad clicked
        public void onAdClick(object sender,ATAdEventArgs erg)
    {
          Debug.Log("Developer onAdClick------" + erg.placementId);
    }

5. Sample Code

java Copy 
public class ExampleHomeScreen : MonoBehaviour, ATSDKInitListener
{    
       void Start()
       {
       #if UNITY_ANDROID
        ATSDKAPI.initSDK("Your Android AppId", "Your Android AppKey", this);
#elif UNITY_IOS || UNITY_IPHONE
        ATSDKAPI.initSDK("Your iOS AppId", "Your iOS AppKey", this);
#endif
       }

      void OnDestroy()
    {
        ATSplashAd.Instance.client.onAdLoadEvent -= onAdLoad;
        ATSplashAd.Instance.client.onAdLoadTimeoutEvent -= onAdLoadTimeout;
        ATSplashAd.Instance.client.onAdLoadFailureEvent -= onAdLoadFailed;
                ATSplashAd.Instance.client.onAdCloseEvent -= onAdClose;
    }

      // SDK initialization succeeded
       public void initSuccess()
       {
        ATSplashAd.Instance.client.onAdLoadEvent += onAdLoad;
        ATSplashAd.Instance.client.onAdLoadTimeoutEvent += onAdLoadTimeout;
        ATSplashAd.Instance.client.onAdLoadFailureEvent += onAdLoadFailed;
        ATSplashAd.Instance.client.onAdCloseEvent += onAdClose;
        ATSplashManager.Instance.ShowAdIfReady();
       }

        public void initFail(string msg)
    {
          Debug.Log("Developer callback SDK initFail:" + msg);
    }
        // Ad loading succeeded, display directly
          public void onAdLoad(object sender, ATAdEventArgs erg)
    {
           if (!erg.isTimeout)
        {
            ATSplashManager.Instance.ShowAdIfReady();
        }
        else 
        {
            // Load timed out, do not call show to display the ad
        }
    } 
      // Ad load timed out, no need to continue waiting for ad fill, go directly to the home page
       public void onAdLoadTimeout(object sender, ATAdEventArgs erg)
       {

       }
        // Ad loading failed
    public void onAdLoadFailed(object sender, ATAdErrorEventArgs args)
    {

    }
      // Ad dismissed, enter the home page
      public void onAdClose(object sender, ATAdEventArgs erg)
    {

    }
         // Listen for APP foreground events
       private void OnApplicationPause(bool pauseStatus)
       {
         if (!pauseStatus)    // Return to foreground from background
         {
             ATSplashManager.Instance.ShowAdIfReady();
         }
       }
}

public class ATSplashManager
    {
#if UNITY_ANDROID
        private const string SPLASH_PLACEMENT_ID = "Your PlacementId";
#elif UNITY_IOS || UNITY_IPHONE
        private static string SPLASH_PLACEMENT_ID = "Your PlacementId";
#endif

        private static ATSplashManager instance = new ATSplashManager();

        public static ATSplashManager Instance
        {
            get
            {
                return instance;
            }
        }

        public void ShowAdIfReady()
        {
            var splashAd = ATSplashAd.Instance;
            if (splashAd.hasSplashAdReady(SPLASH_PLACEMENT_ID))
            {
                splashAd.showSplashAd(SPLASH_PLACEMENT_ID, new Dictionary());
            }
            else
            {
                splashAd.loadSplashAd(SPLASH_PLACEMENT_ID, new Dictionary());
            }
        }
    }
Previous
Native
Next
Callback information description
Last modified: 2026-07-03Powered by