Menu

Banner Ads

1. Integration Suggestions

1.1 Width and Height Settings

  • You can customize the width and height, but they must be consistent with the aspect ratio configured in the TopOn dashboard, and should be adjusted based on the actual effect. For the specific implementation, please refer to the Demo.

1.2 Auto Refresh

  • Disabled by default. You can enable it or disable refresh by configuring the refresh interval in the Ad Placement advanced settings in the TopOn dashboard.
  • The Banner ad View must be added to the window and visible before auto refresh is triggered.
  • If the ad platform provides an auto refresh feature, we recommend disabling the ad platform's auto refresh and using only the auto refresh provided by TopOn, to avoid conflicts that may cause unpredictable issues.
  • After enabling auto refresh, add ATBannerView to the layout, ensure it is visible, and then call the load() method once. After that, display and refresh will be performed automatically by the SDK.
  • Disabled by default. You can enable it or disable refresh by configuring the refresh interval in the Ad Placement advanced settings in the TopOn dashboard.
  • The Banner ad View must be added to the window and visible before auto refresh is triggered.
  • If the ad platform provides an auto refresh feature, we recommend disabling the ad platform's auto refresh and using only the auto refresh provided by TopOn, to avoid conflicts that may cause unpredictable issues.
  • After enabling auto refresh, add TUBannerView to the layout, ensure it is visible, and then call the load() method once. After that, display and refresh will be performed automatically by the SDK.

1.3 Destroy Resources

  • When you no longer need to display the Banner ad, remove ATBannerView from the layout and call the ATBannerView#destroy() method to destroy the current ad resources.
  • When you no longer need to display the Banner ad, remove TUBannerView from the layout and call the TUBannerView#destroy() method to destroy the current ad resources.

java Copy
ATBannerView mBannerView = new ATBannerView(activity);
mBannerView.setPlacementId("your placment id");

//Set the layout parameters for the ad view mBannerView
//Set a width value, such as the screen width
int width = getResources().getDisplayMetrics().widthPixels;
int height = ViewGroup.LayoutParams.WRAP_CONTENT;
mBannerView.setLayoutParams(new FrameLayout.LayoutParams(width, height));

//Add ATBannerView to the ad container
//If you want to manually control when the ad is displayed, you can call this method at an appropriate time based on your own business logic
frameLayout.addView(mBannerView);

mBannerView.setBannerAdListener(new ATBannerListener() {
    @Override
    public void onBannerLoaded() {}

    @Override
    public void onBannerFailed(AdError adError) {
        //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 lag
    }

    @Override
    public void onBannerClicked(ATAdInfo adInfo) {}

    @Override
    public void onBannerShow(ATAdInfo adInfo) {}

    @Override
    public void onBannerClose(ATAdInfo adInfo) {
        if (mBannerView != null && mBannerView.getParent() != null) {
            ((ViewGroup) mBannerView.getParent()).removeView(mBannerView);
        }
    }

    @Override
    public void onBannerAutoRefreshed(ATAdInfo adInfo) {}

    @Override
    public void onBannerAutoRefreshFail(AdError adError) {}
});
//You can set the width and height of the Banner ad returned by the ad platform through ATAdConst.KEY.AD_WIDTH and ATAdConst.KEY.AD_HEIGHT
//The ad platforms that currently support setting width and height are: AdColony, Mintegral, Pangle, UnityAds, Yandex, Admob
//Assume the Banner ad width and height are 320x50
Map localMap = new HashMap<>();
localMap.put(ATAdConst.KEY.AD_WIDTH, dip2px(320));
localMap.put(ATAdConst.KEY.AD_HEIGHT, dip2px(50));
mBannerView.setLocalExtra(localMap);

mBannerView.loadAd();

public int dip2px(int dipValue) {
    float scale = getResources().getDisplayMetrics().density;
    return (int) (dipValue * scale + 0.5f);
}
java Copy
TUBannerView mBannerView = new TUBannerView(activity);
mBannerView.setPlacementId("your placment id");

//Set the layout parameters for the ad view mBannerView
//Set a width value, such as the screen width
int width = getResources().getDisplayMetrics().widthPixels;
int height = ViewGroup.LayoutParams.WRAP_CONTENT;
mBannerView.setLayoutParams(new FrameLayout.LayoutParams(width, height));

//Add TUBannerView to the ad container
//If you want to manually control when the ad is displayed, you can call this method at an appropriate time based on your own business logic
frameLayout.addView(mBannerView);

mBannerView.setBannerAdListener(new TUBannerListener() {
    @Override
    public void onBannerLoaded() {}

    @Override
    public void onBannerFailed(AdError adError) {
        //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 lag
    }

    @Override
    public void onBannerClicked(TUAdInfo adInfo) {}

    @Override
    public void onBannerShow(TUAdInfo adInfo) {}

    @Override
    public void onBannerClose(TUAdInfo adInfo) {
        if (mBannerView != null && mBannerView.getParent() != null) {
            ((ViewGroup) mBannerView.getParent()).removeView(mBannerView);
        }
    }

    @Override
    public void onBannerAutoRefreshed(TUAdInfo adInfo) {}

    @Override
    public void onBannerAutoRefreshFail(AdError adError) {}
});
//You can set the width and height of the Banner ad returned by the ad platform through TUAdConst.KEY.AD_WIDTH and TUAdConst.KEY.AD_HEIGHT
//The ad platforms that currently support setting width and height are: AdColony, Mintegral, Pangle, UnityAds, Yandex, Admob
//Assume the Banner ad width and height are 320x50
Map localMap = new HashMap<>();
localMap.put(TUAdConst.KEY.AD_WIDTH, dip2px(320));
localMap.put(TUAdConst.KEY.AD_HEIGHT, dip2px(50));
mBannerView.setLocalExtra(localMap);

mBannerView.loadAd();

public int dip2px(int dipValue) {
    float scale = getResources().getDisplayMetrics().density;
    return (int) (dipValue * scale + 0.5f);
}

3. 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 setShowConfig()
  3. Finally, display the ad
Method Description
void entryAdScenario(String placementId, String scenarioId) Track the cache status statistics of the current ad placement when entering a business scenario. For specific 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) (v6.5.80 and above) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario.
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional, passing null will count toward the default scenario)
void setShowConfig(ATShowConfig showConfig) Set the ad scenario (for subsequent ad display).
showConfig: Additional parameters can be passed in at display time, as follows
1.ATShowConfig#showCustomExt(String showCustomExt): A custom parameter can be passed in at display time. Passing this parameter will return it through ATAdInfo#getShowCustomExt()
2.ATShowConfig#scenarioId(String scenarioId): An Ad Scenario ID can be passed in
Method Description
void entryAdScenario(String placementId, String scenarioId) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario.
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional, passing null will count toward the default scenario)
void setShowConfig(TUShowConfig showConfig) Set the ad scenario (for subsequent ad display).
showConfig: Additional parameters can be passed in at display time, as follows
1.TUShowConfig#showCustomExt(String showCustomExt): A custom parameter can be passed in at display time. Passing this parameter will return it through TUAdInfo#getShowCustomExt()
2.TUShowConfig#scenarioId(String scenarioId): An Ad Scenario ID can be passed in

4. API Description

● ATBannerView

The Banner ad operation class, responsible for ad loading, listening, display, etc.

Method Description
ATBannerView(Context context) Banner ad initialization method
context: Context, an Activity is recommended.
Note: If you have integrated Mintegral, UnityAds, AdColony, Applovin, Chartboost, Kidoz, Pangle, or StartApp, the first parameter must be an Activity
void setLocalExtra(Map map) Set custom information before loading the ad or at display time
void setBannerAdListener(ATBannerListener listener) Set the Ad Placement-level ad listener callback
listener: The ad placement event callback interface class
void load() Start loading the ad
void entryAdScenario(String placementId, String scenarioId) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario
placementId: Banner style ad placement, obtained by creating a Banner Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, you can pass null directly), can be created as a scenario parameter in the dashboard
void entryAdScenario(String scenarioId) (v6.5.80 and above) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario
placementId: Banner style ad placement, obtained by creating a Banner Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, you can pass null directly), can be created as a scenario parameter in the dashboard

● ATBannerListener

Ad Placement-level Ad Event Callbacks

Method Description
void onBannerLoaded() Ad load success callback
void onBannerFailed(AdError error) Ad load failure callback. You can get all error information through 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 lag
void onBannerShow(ATAdInfo adInfo) Ad display callback
adInfo: Ad information object
void onBannerClicked(ATAdInfo adInfo) Ad click callback
adInfo: Ad information object
void onBannerClose(ATAdInfo adInfo) Ad close callback
adInfo: Ad information object
void onBannerAutoRefreshed(ATAdInfo adInfo) Ad auto refresh callback
adInfo: Ad information object
void onBannerAutoRefreshFail(ATAdInfo adInfo) Ad auto refresh failure callback
adInfo: Ad information object

● TUBannerView

The Banner ad operation class, responsible for ad loading, listening, display, etc.

Method Description
TUBannerView(Context context) Banner ad initialization method
context: Context, an Activity is recommended.
Note: If you have integrated Mintegral, UnityAds, AdColony, Applovin, Chartboost, Kidoz, Pangle, or StartApp, the first parameter must be an Activity
void setLocalExtra(Map map) Set custom information before loading the ad or at display time
void setBannerAdListener(TUBannerListener listener) Set the Ad Placement-level ad listener callback
listener: The ad placement event callback interface class
void load() Start loading the ad
void entryAdScenario(String placementId, String scenarioId) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario
placementId: Banner style ad placement, obtained by creating a Banner Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, you can pass null directly), can be created as a scenario parameter in the dashboard
void entryAdScenario(String scenarioId) (6.5.80 and above) Track the cache status statistics of the current ad placement when entering a business scenario. For specific usage, see Ad Scenario
placementId: Banner style ad placement, obtained by creating a Banner Ad Placement in the TopOn dashboard
scenarioId: Ad Scenario (optional, you can pass null directly), can be created as a scenario parameter in the dashboard

● TUBannerListener

Ad Placement-level Ad Event Callbacks

Method Description
void onBannerLoaded() Ad load success callback
void onBannerFailed(AdError error) Ad load failure callback. You can get all error information through 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 lag
void onBannerShow(TUBannerAdInfo adInfo) Ad display callback
adInfo: Ad information object
void onBannerClicked(TUBannerAdInfo adInfo) Ad click callback
adInfo: Ad information object
void onBannerClose(TUBannerAdInfo adInfo) Ad close callback
adInfo: Ad information object
void onBannerAutoRefreshed(TUBannerAdInfo adInfo) Ad auto refresh callback
adInfo: Ad information object
void onBannerAutoRefreshFail(TUBannerAdInfo adInfo) Ad auto refresh failure callback
adInfo: Ad information object

5. Advanced Settings

Custom Banner Ad: Configure native ads using a Banner placement.

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


6. Integration Reference

Sample Code: BannerAdActivity.java in the Demo


7. Ad Network Specific Configuration Instructions

The TopOn SDK supports AdMob's adaptive banners, including anchored adaptive banners and inline adaptive banners. It is recommended to use anchored adaptive banners. You need to use the following code to set the type of adaptive banner, which screen orientation to adapt to, and the width of the banner (unit: px). The sample code is as follows:

java Copy
ATBannerView mBannerView = new ATBannerView(activity);
mBannerView.setPlacementId("your placement id");
Map localExtra = new HashMap<>();

//since v5.7.0, Admob Adaptive banner (anchored adaptive banner, large-size adaptive banner)
localExtra.put(AdmobATConst.ADAPTIVE_TYPE, AdmobATConst.ADAPTIVE_ANCHORED);//anchored adaptive banner
//localExtra.put(AdmobATConst.ADAPTIVE_TYPE, AdmobATConst.ADAPTIVE_INLINE);//large-size adaptive banner

localExtra.put(AdmobATConst.ADAPTIVE_ORIENTATION, AdmobATConst.ORIENTATION_CURRENT);
//localExtra.put(AdmobATConst.ADAPTIVE_ORIENTATION, AdmobATConst.ORIENTATION_PORTRAIT);
//localExtra.put(AdmobATConst.ADAPTIVE_ORIENTATION, AdmobATConst.ORIENTATION_LANDSCAPE);

localExtra.put(AdmobATConst.ADAPTIVE_WIDTH, width);

mBannerView.setLocalExtra(localExtra);

mBannerView.loadAd();
java Copy
TUBannerView mBannerView = new TUBannerView(activity);
mBannerView.setPlacementId("your placement id");
Map localExtra = new HashMap<>();

//since v5.7.0, Admob Adaptive banner (anchored adaptive banner, large-size adaptive banner)
localExtra.put(AdmobTUConst.ADAPTIVE_TYPE, AdmobTUConst.ADAPTIVE_ANCHORED);//anchored adaptive banner
//localExtra.put(AdmobTUConst.ADAPTIVE_TYPE, AdmobTUConst.ADAPTIVE_INLINE);//large-size adaptive banner

localExtra.put(AdmobTUConst.ADAPTIVE_ORIENTATION, AdmobTUConst.ORIENTATION_CURRENT);
//localExtra.put(AdmobTUConst.ADAPTIVE_ORIENTATION, AdmobTUConst.ORIENTATION_PORTRAIT);
//localExtra.put(AdmobTUConst.ADAPTIVE_ORIENTATION, AdmobTUConst.ORIENTATION_LANDSCAPE);

localExtra.put(AdmobTUConst.ADAPTIVE_WIDTH, width);

mBannerView.setLocalExtra(localExtra);

mBannerView.loadAd();

Note: When using AdMob's adaptive banner, you cannot restrict the height of the Banner parent container. The example is as follows:

java Copy
mBannerView.setLayoutParams(new FrameLayout.LayoutParams(width, ViewGroup.LayoutParams.WRAP_CONTENT));
mBannerView.loadAd();
Previous
Customized Splash ads
Next
Customized banner ads
Last modified: 2026-07-08Powered by