Menu

Splash Ads

1. Integration Suggestions

⚠️ Note

  • The ad load timeout duration is the maximum time allowed to wait for the splash ad to load (it only covers waiting for the ad to load; it does not include the time for displaying the ad).
  • If the passed timeout duration is too short or the passed timeout duration is not used as the splash ad load waiting time, it may affect the effectiveness of the splash ad.

It is recommended that you call this step in advance to reduce the waiting time caused by the ad loading time for users.

d when the current Activity is in the foreground
if (inForeBackground) {
//The container size must cover at least 75% of the screen
splashAd.show(activity, container);
}
}

Copy
@Override
public void onNoAdError(AdError adError) {
    //On load failure, go directly to the main screen
    ...
}

@Override
public void onAdShow(TUAdInfo adInfo) { }

@Override
public void onAdClick(TUAdInfo adInfo) { }

@Override
public void onAdDismiss(TUAdInfo adInfo, TUSplashAdExtraInfo splashAdExtraInfo) {
    if (container != null) {
      container.removeAllViews();
    }
    // For hot-start Splash Ad, pre-load is recommended
    // splashAd.loadAd();
    //Enter the main screen after the Splash Ad is dismissed
    ...
}

}, xxxx); // Note: xxx should be replaced with your Splash Ad timeout, in milliseconds
splashAd.loadAd();

Copy
</div>



---

## 3. Display an Ad

> **💡Tips:**
>
> - Before displaying the ad, it is recommended to first call `splashAd#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.
> - Before displaying the splash ad, you need to check whether the current Activity is in the foreground.
> - The container for displaying the splash ad must be at least 75% of the screen size.


<div class="code-at code-hidden">

```java
if(splashAd.isAdReady()){
    ATShowConfig showConfig = new ATShowConfig.Builder().scenarioId("your scenario id").build();
    //The container size must cover at least 75% of the screen
    splashAd.show(activity, container, null, showConfig);
}else{
    //Reload
    splashAd.load();
}
java Copy
if(splashAd.isAdReady()){
    TUShowConfig showConfig = new TUShowConfig.Builder().scenarioId("your scenario id").build();
    //The container size must cover at least 75% of the screen
    splashAd.show(activity, container, null, showConfig);
}else{
    //Reload
    splashAd.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
ATSplashAd.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
splashAd.entryAdScenario("your scenario id");
if (splashAd.isAdReady()) {
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    splashAd.show(activity,showConfig);
} else {
   splashAd.load();
}
java Copy
TUSplashAd.entryAdScenario("your placement id", "your scenario id");
//6.5.80 and above
splashAd.entryAdScenario("your scenario id");
if (splashAd.isAdReady()) {
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    splashAd.show(activity,showConfig);
} else {
   splashAd.load();
}

5. API Description

● ATSplashAd

Splash Ad operation class, responsible for ad loading, listening, display, etc.

Method Description
ATSplash(Context context, String placmentId, ATSplashAdEZListener listener, int fetchAdTimeout) Splash Ad initialization method
context: Context, Activity is recommended. placmentId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
listener: placement-level ad event listener callback fetchAdTimeout: ad loading timeout, in milliseconds
Note: The ad loading timeout defaults to 10000ms
ATSplash(Context context, String placmentId, ATSplashAdEZListener listener) Splash Ad initialization method
context: Context, Activity is recommended
placmentId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
listener: placement-level ad event listener callback
void setLocalExtra(Map map) Set custom information before loading the ad or when displaying it
void setAdListener(ATSplashAdEZListener listener) Set the placement-level ad listener callback, which will override the listener set in the ATSplash constructor
listener: ad placement event callback interface class
void load() Initiate ad loading
boolean isAdReady() Check whether the Ad Placement has an ad available to display Return value:
true = there is an ad available to display
false = there is no ad available to display
void show(Activity activity, ViewGroup container) Show the ad
activity: the activity to display the ad
container: the container to display the ad
void show(Activity activity, ViewGroup container, ATSplashSkipInfo atSplashSkipInfo, ATShowConfig showConfig) Show the ad, passing in custom parameters and Ad Scenario when displaying the ad
activity: the activity to display the ad
container: the container to display the ad
atSplashSkipInfo: custom SkipView utility class, effective only for Adx; refer to the Demo for usage
showConfig: ad display configuration, including custom parameters and Ad Scenario
void entryAdScenario(String placementId, String scenarioId) Enter the business scenario to collect the cache status statistics of the current Ad Placement. For detailed usage, see Ad Scenario
placementId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, can pass null directly), can be obtained from the scenario parameters created in the backend
void entryAdScenario(String scenarioId) (v6.5.80 and above) Enter the business scenario to collect the cache status statistics of the current Ad Placement. For detailed usage, see Ad Scenario
placementId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, can pass null directly), can be obtained from the scenario parameters created in the backend

● ATSplashAdEZListener

Placement-level Ad Event Callbacks

Method Description
void onAdLoaded() Ad load success callback
void onNoAdError(AdError error) Ad load failure callback. You can get all error information via AdError.getFullErrorInfo()
error: error information
Note: Do not call the ad loading method to retry in this callback, otherwise it will trigger many useless requests and may cause app lag
void onAdShow(ATAdInfo adInfo) Ad display callback
adInfo: ad information object
void onAdClick(ATAdInfo adInfo) Ad click callback
adInfo: ad information object
void onAdDismiss(ATAdInfo adInfo, ATSplashAdExtraInfo splashAdExtraInfo) Ad dismiss callback
adInfo: ad information object
splashAdExtraInfo: extra information when the Splash Ad is dismissed

● TUSplashAd

Splash Ad operation class, responsible for ad loading, listening, display, etc.

Method Description
TUSplash(Context context, String placmentId, TUSplashAdEZListener listener, int fetchAdTimeout) Splash Ad initialization method
context: Context, Activity is recommended
placmentId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
listener: placement-level ad event listener callback
fetchAdTimeout: ad loading timeout, in milliseconds
Note: The ad loading timeout defaults to 10000ms
TUSplash(Context context, String placmentId, TUSplashAdEZListener listener) Splash Ad initialization method
context: Context, Activity is recommended
placmentId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
listener: placement-level ad event listener callback
void setLocalExtra(Map map) Set custom information before loading the ad or when displaying it
void setAdListener(TUSplashAdEZListener listener) Set the placement-level ad listener callback, which will override the listener set in the TUSplash constructor
listener: ad placement event callback interface class
void load() Initiate ad loading
boolean isAdReady() Check whether the Ad Placement has an ad available to display Return value:
true = there is an ad available to display
false = there is no ad available to display
void show(Activity activity, ViewGroup container) Show the ad
activity: the activity to display the ad
container: the container to display the ad
void show(Activity activity, ViewGroup container, TUSplashSkipInfo atSplashSkipInfo, TUShowConfig showConfig) Show the ad, passing in custom parameters and Ad Scenario when displaying the ad
activity: the activity to display the ad
container: the container to display the ad
atSplashSkipInfo: custom SkipView utility class, effective only for Adx; refer to the Demo for usage
showConfig: ad display configuration, including custom parameters and Ad Scenario
void entryAdScenario(String placementId, String scenarioId) Enter the business scenario to collect the cache status statistics of the current Ad Placement. For detailed usage, see Ad Scenario
placementId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, can pass null directly), can be obtained from the scenario parameters created in the backend
void entryAdScenario(String scenarioId) (v6.5.80 and above) Enter the business scenario to collect the cache status statistics of the current Ad Placement. For detailed usage, see Ad Scenario
placementId: Splash Ad Placement, obtained by creating a Splash Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, can pass null directly), can be obtained from the scenario parameters created in the backend

● TUSplashAdEZListener

Placement-level Ad Event Callbacks

Method Description
void onAdLoaded() Ad load success callback
void onNoAdError(AdError error) Ad load failure callback. You can get all error information via AdError.getFullErrorInfo()
error: error information
Note: Do not call the ad loading method to retry in this callback, otherwise it will trigger many useless requests and may cause app lag
void onAdShow(TUAdInfo adInfo) Ad display callback
adInfo: ad information object
void onAdClick(TUAdInfo adInfo) Ad click callback
adInfo: ad information object
void onAdDismiss(TUAdInfo adInfo, TUSplashAdExtraInfo splashAdExtraInfo) Ad dismiss callback
adInfo: ad information object
splashAdExtraInfo: extra information when the Splash Ad is dismissed

6. Advanced Settings

Custom Splash Ad: Configure native ads using a Splash ad placement.

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


7. Integration Reference

Sample Code: SplashAdActivity.java in the Demo


8. Ad Network Specific Configuration Instructions

● AdMob

AdMob's splash ad does not require a container for display. It can only be displayed fullscreen. After the ad is displayed, no countdown timer will appear and it will not auto-skip.

Previous
Customized Interstitial Ad
Next
Best practices for Splash Ads
Last modified: 2026-07-08Powered by