Menu

Native Ads

1. Integration Suggestions

Type Description Notes
Self-Rendering The third-party ad platform returns the ad materials, and the developer assembles them into the ad type. The type selected on the third-party dashboard must match the TopOn dashboard; otherwise the request will fail. Self-Rendering Native Ad Notes
template rendering The third-party ad platform returns a rendered view, and the developer simply adds it to a container to display it. - A template ad has its own aspect ratio, which can be viewed on the ad platform's dashboard. Try to select a template with the same or a similar aspect ratio on the ad platform's dashboard , and pass that aspect ratio's width and height in the code to load and display the ad for the best display effect.
- The width and height of ATNativeAdView must match those corresponding to ATAdConst.KEY.AD_WIDTH and ATAdConst.KEY.AD_HEIGHT; otherwise the ad may be displayed incompletely or too small.
Type Description Notes
Self-Rendering The third-party ad platform returns the ad materials, and the developer assembles them into the ad type. The type selected on the third-party dashboard must match the TopOn dashboard; otherwise the request will fail. Self-Rendering Native Ad Notes
template rendering The third-party ad platform returns a rendered view, and the developer simply adds it to a container to display it. - A template ad has its own aspect ratio, which can be viewed on the ad platform's dashboard. Try to select a template with the same or a similar aspect ratio on the ad platform's dashboard , and pass that aspect ratio's width and height in the code to load and display the ad for the best display effect.
- The width and height of TUNativeAdView must match those corresponding to TUAdConst.KEY.AD_WIDTH and TUAdConst.KEY.AD_HEIGHT; otherwise the ad may be displayed incompletely or too small.

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

java Copy
//Initialize the ad loading object
ATNative atNative = new ATNative(context, "your placement id", new ATNativeNetworkListener() {
    @Override
    public void onNativeAdLoaded() {
        // Reset the retry load count
        retryAttempt = 0;
    }
    
    @Override
    public void onNativeAdLoadFail(AdError adError) {
        // Load failure callback
        // We recommend extending the retry interval exponentially until reaching the maximum delay (8 seconds in this example) or the maximum number of retries (3 in this example)
        if (retryAttempt >= 3) return;
        retryAttempt++;
        long delayMillis = TimeUnit.SECONDS.toMillis((long) Math.pow(2, Math.min(3, retryAttempt)));
        new Handler().postDelayed(new Runnable() {
            @Override
            public void run() {
                mNativeAdLoader.loadAd();
            }
        }, delayMillis);
    }
});
//Make the ad request
atNative.makeAdRequest();
java Copy
//Initialize the ad loading object
TUNative tuNative = new TUNative(context, "your placement id", new TUNativeNetworkListener() {
    @Override
    public void onNativeAdLoaded() {
        // Reset the retry load count
        retryAttempt = 0;
    }
    
    @Override
    public void onNativeAdLoadFail(AdError adError) {
        // Load failure callback
        // We recommend extending the retry interval exponentially until reaching the maximum delay (8 seconds in this example) or the maximum number of retries (3 in this example)
        if (retryAttempt >= 3) return;
        retryAttempt++;
        long delayMillis = TimeUnit.SECONDS.toMillis((long) Math.pow(2, Math.min(3, retryAttempt)));
        new Handler().postDelayed(new Runnable() {
            @Override
            public void run() {
                mNativeAdLoader.loadAd();
            }
        }, delayMillis);
    }
});
//Make the ad request
tuNative.makeAdRequest();

Note: Before displaying the ad, we recommend reviewing the Self-Rendering Native Ad Notes to avoid display and click anomalies.

Use ATNative#getNativeAd() to get the ad object NativeAd . The steps are as follows:

(1) Use the NativeAd isNativeExpress method to determine whether it is Self-Rendering or template rendering

Rendering Method Implementation Steps
Self-Rendering ① Bind the material Views through the ATNativePrepareInfo object.
② Call NativeAd#getAdMaterial() to get the ad material object ATNativeMaterial
③ Call NativeAd#renderAdContainer(ATNativeAdView, View) to render. The ATNativeAdView parameter can be created directly or defined in the layout; the View parameter is the custom layout.
④ Call NativeAd#prepare(ATNativeAdView, ATNativePrepareInfo) ; the ATNativePrepareInfo parameter is the ATNativePrepareInfo object from step one.
template rendering ① Call the NativeAd renderAdContainer(ATNativeAdView, View) method to render. The ATNativeAdView parameter can be created directly or defined in the layout; pass null for the View parameter.
② Call the NativeAd prepare(ATNativeAdView, ATNativePrepareInfo) method, passing null for the ATNativePrepareInfo parameter.

(2) Sample code is as follows:

java Copy
//Rendering an ad requires creating a container, which can be defined in the XML layout (refer to the Demo https://github.com/toponteam/TPN-Android-Demo)
ATNativeAdView mATNativeAdView = findViewById(R.id.native_ad_view);
//Custom layout container, which can be defined in the XML layout
View mSelfRenderView = mATNativeAdView.findViewById(R.id.native_selfrender_view);
NativeAd mNativeAd= atNative.getNativeAd();
//After calling getNativeAd, you can directly use ATNative#makeAdRequest to preload the next ad
if (mNativeAd != null) {
    mNativeAd.setNativeEventListener(new ATNativeEventListener() {
        @Override
        public void onAdImpressed(ATNativeAdView view, ATAdInfo adInfo) {}
        
        @Override
        public void onAdClicked(ATNativeAdView view, ATAdInfo adInfo) {}
        
        @Override
        public void onAdVideoStart(ATNativeAdView view) {}
        
        @Override
        public void onAdVideoEnd(ATNativeAdView view) {}
        
        @Override
        public void onAdVideoProgress(ATNativeAdView view, int progress) {}
    });
    if (mNativeAd.isNativeExpress()) {
        //template rendering
        mNativeAd.renderAdContainer(mATNativeAdView, null);
        mNativeAd.prepare(mATNativeAdView, null);
    } else {
        //Self-Rendering
        ATNativePrepareInfo nativePrepareInfo = new ATNativePrepareInfo();
        //The bindSelfRenderView() method binds materials in the Self-Rendering approach
        //For method details, refer to https://github.com/toponteam/TPN-Android-Demo/blob/main/NonChina_Jcenter/demo/app/src/main/java/com/test/ad/demo/SelfRenderViewUtil.java
        bindSelfRenderView(activity, mNativeAd.getAdMaterial(), mSelfRenderView, nativePrepareInfo);
        mNativeAd.renderAdContainer(mATNativeAdView, mSelfRenderView);
        mNativeAd.prepare(mATNativeAdView, nativePrepareInfo);
    }
}

Note: Before displaying the ad, we recommend reviewing the Self-Rendering Native Ad Notes to avoid display and click anomalies.

Use TUNative#getNativeAd() to get the ad object NativeAd . The steps are as follows:

(1) Use the NativeAd isNativeExpress method to determine whether it is Self-Rendering or template rendering

Rendering Method Implementation Steps
Self-Rendering ① Bind the material Views through the ATNativePrepareInfo object.
② Call NativeAd#getAdMaterial() to get the ad material object TUNativeMaterial
③ Call NativeAd#renderAdContainer(TUNativeAdView, View) to render. The ATNativeAdView parameter can be created directly or defined in the layout; the View parameter is the custom layout.
④ Call NativeAd#prepare(TUNativeAdView, TUNativePrepareInfo) ; the TUNativePrepareInfo parameter is the ATNativePrepareInfo object from step one.
template rendering ① Call the NativeAd renderAdContainer(TUNativeAdView, View) method to render. The TUNativeAdView parameter can be created directly or defined in the layout; pass null for the View parameter.
② Call the NativeAd prepare(TUNativeAdView, TUNativePrepareInfo) method, passing null for the TUNativePrepareInfo parameter.

(2) Sample code is as follows:

java Copy
//Rendering an ad requires creating a container, which can be defined in the XML layout (refer to the Demo https://github.com/toponteam/TPN-Android-Demo)
TUNativeAdView mTUNativeAdView = findViewById(R.id.native_ad_view);
//Custom layout container, which can be defined in the XML layout
View mSelfRenderView = mTUNativeAdView.findViewById(R.id.native_selfrender_view);
NativeAd mNativeAd= atNative.getNativeAd();
//After calling getNativeAd, you can directly use TUNative#makeAdRequest to preload the next ad
if (mNativeAd != null) {
    mNativeAd.setNativeEventListener(new TUNativeEventListener() {
        @Override
        public void onAdImpressed(TUNativeAdView view, TUNativeAdInfo adInfo) {}
        
        @Override
        public void onAdClicked(TUNativeAdView view, TUNativeAdInfo adInfo) {}
        
        @Override
        public void onAdVideoStart(TUNativeAdView view) {}
        
        @Override
        public void onAdVideoEnd(TUNativeAdView view) {}
        
        @Override
        public void onAdVideoProgress(TUNativeAdView view, int progress) {}
    });
    if (mNativeAd.isNativeExpress()) {
        //template rendering
        mNativeAd.renderAdContainer(mTUNativeAdView, null);
        mNativeAd.prepare(mTUNativeAdView, null);
    } else {
        //Self-Rendering
        ATNativePrepareInfo nativePrepareInfo = new ATNativePrepareInfo();
        //The bindSelfRenderView() method binds materials in the Self-Rendering approach
        //For method details, refer to https://github.com/toponteam/TPN-Android-Demo/blob/main/NonChina_Jcenter/demo/app/src/main/java/com/test/ad/demo/SelfRenderViewUtil.java
        bindSelfRenderView(activity, mNativeAd.getAdMaterial(), mSelfRenderView, nativePrepareInfo);
        mNativeAd.renderAdContainer(mTUNativeAdView, mSelfRenderView);
        mNativeAd.prepare(mTUNativeAdView, nativePrepareInfo);
    }
}

4. Ad Scenario Statistics

Track scenario reach rate , shown in the dashboard data under Data Reports -> Funnel Analysis Report -> Reached Ad Scenario. We recommend calling it in the right place.

  1. First call entryAdScenario()
  2. Then call getNativeAd(ATShowConfig showConfig)
  3. Finally display the ad
Method Description
void entryAdScenario(String placementId, String scenarioId) Enters the business scenario to track the current ad placement's cache status. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null counts toward the default scenario)
void entryAdScenario(String scenarioId) (v6.5.80 and above) Enters the business scenario to track the current ad placement's cache status. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null counts toward the default scenario)
NativeAd getNativeAd(ATShowConfig showConfig) (Added in v6.3.10) Gets an ad that has finished loading (we recommend performing a non-null check after getting it) and sets the ad scenario for the subsequent ad display
showConfig: additional parameters can be passed at display time, as follows
1.ATShowConfig#showCustomExt(String showCustomExt) : a custom parameter can be passed at display time; passing this parameter will return it through ATAdInfo#getShowCustomExt()
2.ATShowConfig#scenarioId(String scenarioId) : an Ad Scenario ID can be passed
java Copy
ATNative.entryAdScenario("your placement id", "your scenario id");
//v6.5.80 and above
mATNative.entryAdScenario("your scenario id");
......
ATShowConfig.Builder builder = new ATShowConfig.Builder();
builder.scenarioId("your scenario id");
builder.showCustomExt("your custom data");
// Note: This method must be called before displaying the ad
mATNative.getNativeAd(builder.build());

Track scenario reach rate , shown in the dashboard data under Data Reports -> Funnel Analysis Report -> Reached Ad Scenario. We recommend calling it in the right place.

  1. First call entryAdScenario()
  2. Then call getNativeAd(TUShowConfig showConfig)
  3. Finally display the ad
Method Description
void entryAdScenario(String placementId, String scenarioId) Enters the business scenario to track the current ad placement's cache status. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null counts toward the default scenario)
void entryAdScenario(String scenarioId) (v6.5.80 and above) Enters the business scenario to track the current ad placement's cache status. For detailed usage, see Ad Scenario
placementId: Ad Placement ID
scenarioId: Ad Scenario ID (optional; passing null counts toward the default scenario)
NativeAd getNativeAd(ATShowConfig showConfig) (Added in v6.3.10) Gets an ad that has finished loading (we recommend performing a non-null check after getting it) and sets the ad scenario for the subsequent ad display showConfig: additional parameters can be passed at display time, as follows
1.TUShowConfig#showCustomExt(String showCustomExt) : a custom parameter can be passed at display time; passing this parameter will return it through ATAdInfo#getShowCustomExt()
2.TUShowConfig#scenarioId(String scenarioId) : an Ad Scenario ID can be passed
java Copy
TUNative.entryAdScenario("your placement id", "your scenario id");
//v6.5.80 and above
mTUNative.entryAdScenario("your scenario id");
......
TUShowConfig.Builder builder = new TUShowConfig.Builder();
builder.scenarioId("your scenario id");
builder.showCustomExt("your custom data");
// Note: This method must be called before displaying the ad
mTUNative.getNativeAd(builder.build());

5. Destroy Resources

💡Tips: When you no longer need to display the Native Ad, remove the Native Ad-related Views from the layout and call the NativeAd destory method to destroy the current ad resources.

java Copy
@Override
protected void onDestroy() {
    super.onDestroy();
    if (mNativeAd != null) {
        mNativeAd.destory();
    }
    if (mATNative != null) {
        mATNative.setAdListener(null);
        mATNative.setAdSourceStatusListener(null);
        mATNative.setAdMultipleLoadedListener(null);
    }
}

💡Tips: When you no longer need to display the Native Ad, remove the Native Ad-related Views from the layout and call the NativeAd destory method to destroy the current ad resources.

java Copy
@Override
protected void onDestroy() {
    super.onDestroy();
    if (mNativeAd != null) {
        mNativeAd.destory();
    }
    if (mTUNative != null) {
        mTUNative.setAdListener(null);
        mTUNative.setAdSourceStatusListener(null);
        mTUNative.setAdMultipleLoadedListener(null);
    }
}

6. Close Button (Optional)

(1) You can bind the close button by calling the ATNativePrepareInfo#setCloseView() method to set the close button into ATNativePrepareInfo.

Note: This must be called before the prepare method.

java Copy
ATNativePrepareInfo nativePrepareInfo = new ATNativePrepareInfo();
View selfRenderView = LayoutInflater.from(activity).inflate(R.layout.native_selfrender_view, null);
bindSelfRenderView(activity, mNativeAd.getAdMaterial(), selfRenderView, nativePrepareInfo);
//Render the ad
mNativeAd.renderAdContainer(mATNativeAdView, selfRenderView);
mNativeAd.prepare(mATNativeAdView, nativePrepareInfo);

//The bindSelfRenderView() method binds materials in the Self-Rendering approach
//For method details, refer to https://github.com/toponteam/TPN-Android-Demo/blob/main/NonChina_Jcenter/demo/app/src/main/java/com/test/ad/demo/SelfRenderViewUtil.java
public void bindSelfRenderView(Context context, ATNativeMaterial adMaterial, View selfRenderView, ATNativePrepareInfo nativePrepareInfo) {
    ...
    //Your own close button
    View closeView = selfRenderView.findViewById(R.id.native_ad_close);
    ...
    nativePrepareInfo.setCloseView(closeView);
    ...
}

(2) After binding the close button correctly, set up the close button listener

java Copy
mNativeAd.setDislikeCallbackListener(new ATNativeDislikeListener() {
   @Override
   public void onAdCloseButtonClick(ATNativeAdView view, ATAdInfo entity) {
       //Here you can implement the ad View removal
   }
});

(1) You can bind the close button by calling the TUNativePrepareInfo#setCloseView() method to set the close button into TUNativePrepareInfo.

Note: This must be called before the prepare method.

java Copy
TUNativePrepareInfo nativePrepareInfo = new TUNativePrepareInfo();
View selfRenderView = LayoutInflater.from(activity).inflate(R.layout.native_selfrender_view, null);
bindSelfRenderView(activity, mNativeAd.getAdMaterial(), selfRenderView, nativePrepareInfo);
//Render the ad
mNativeAd.renderAdContainer(mTUNativeAdView, selfRenderView);
mNativeAd.prepare(mTUNativeAdView, nativePrepareInfo);

//The bindSelfRenderView() method binds materials in the Self-Rendering approach
//For method details, refer to https://github.com/toponteam/TPN-Android-Demo/blob/main/NonChina_Jcenter/demo/app/src/main/java/com/test/ad/demo/SelfRenderViewUtil.java
public void bindSelfRenderView(Context context, TUNativeMaterial adMaterial, View selfRenderView, TUNativePrepareInfo nativePrepareInfo) {
    ...
    //Your own close button
    View closeView = selfRenderView.findViewById(R.id.native_ad_close);
    ...
    nativePrepareInfo.setCloseView(closeView);
    ...
}

(2) After binding the close button correctly, set up the close button listener

java Copy
mNativeAd.setDislikeCallbackListener(new TUNativeDislikeListener() {
   @Override
   public void onAdCloseButtonClick(TUNativeAdView view, TUNativeAdInfo adInfo) {
       //Here you can implement the ad View removal
   }
});

7. API Description

● ATNative

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

Method Description
ATNative(Context context, String placementId, ATNativeNetworkListener listener) Native Ad initialization method
context: the Context; we recommend passing an Activity
placementId: ad ID, obtained by creating a Native Ad Placement in the TopOn dashboard
listener: ad placement event callback listener
void setLocalExtra(Map map) Sets custom information before loading or when displaying the ad
void setAdListener(ATNativeNetworkListener listener) Sets the placement-level ad listener callback
listener: ad placement event callback interface class
void makeAdRequest() Initiates ad loading
NativeAd getNativeAd() Gets the ad object, used to display the ad
Return value: the ad object
NativeAd getNativeAd(ATShowConfig showConfig) (Added in v6.3.10) Gets an ad that has finished loading (we recommend performing a non-null check after getting it) and sets the ad scenario for the subsequent ad display. showConfig: additional parameters can be passed at display time, as follows:
1.ATShowConfig#showCustomExt(String showCustomExt) : a custom parameter can be passed at display time; passing this parameter will return it through ATAdInfo#getShowCustomExt()
2.ATShowConfig#scenarioId(String scenarioId) : an Ad Scenario ID can be passed
void entryAdScenario(String placementId, String scenarioId) Enters the business scenario to track the current ad placement's cache status. For detailed 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), the scenario parameter can be created in the dashboard

● ATNativeNetworkListener

Placement-level Ad Event Callbacks

Method Description
void onNativeAdLoaded() Ad load success callback
void onNativeAdLoadFail(AdError error) Ad load failure callback; you can get all error information through AdError.getFullErrorInfo()
error: error information
Note: Do not perform the ad loading method for retries in this callback; otherwise it will cause many useless requests and may cause the app to lag

● NativeAd

The Native Ad object, used to display the ad

Method Description
void setNativeEventListener(ATNativeEventListener listener) Sets the ad display-related event listener callback
listener: ad display event listener
boolean isNativeExpress() Whether it is a template-rendering ad. Return value:
true = template ad,
false = Self-Rendering ad
ATNativeMaterial getAdMaterial() Gets the ad material object, supported only for Self-Rendering ads
Return value: the ad material object
void renderAdContainer(ATNativeAdView view, View selfRenderView) For ad rendering. view: the ad container provided by TopOn; passing null will cause the display to fail
selfRenderView: the developer's custom View. When isNativeExpress() returns false, selfRenderView must be the developer's custom View; when it returns true, null can be passed
void prepare(ATNativeAdView view, ATNativePrepareInfo nativePrepareInfo) For configuring ad click events, binding self-rendering elements, etc.
view: the ad container provided by TopOn; passing null will cause the display to fail
nativePrepareInfo: used for Self-Rendering ads to bind self-rendering elements and click events, etc.; for template ads null can be passed
Note: The prepare method must be called after the renderAdContainer method, whether Self-Rendering or template rendering
void destory() Destroys the ad; after calling it, the NativeAd object can no longer be used to render or display ads

● ATNativeEventListener

Ad display-related event listener callback

Method Description
void onAdImpressed(ATNativeAdView view, ATAdInfo adInfo) Ad display success callback
view: the ad container
void onAdClicked(ATNativeAdView view, ATAdInfo adInfo) Ad click callback
view: the ad container
adInfo: the ad information object
void onAdVideoStart(ATNativeAdView view) Video ad playback start callback
view: the ad container
void onAdVideoProgress(ATNativeAdView view, int progress) Video ad playback progress callback
view: the ad container
progress: playback progress
void onAdVideoEnd(ATNativeAdView view) Video ad playback end callback
view: the ad container

● ATNativeMaterial

The ad material object returned by Self-Rendering ads ( All returned materials below may be null, because some ad platforms may not have all material information )

Method Description
String getIconImageUrl() Gets the ad icon URL. When both getAdIconView and getIconImageUrl are returned, prefer getAdIconView ; render only one of them
View getAdIconView() Gets the ad IconView. When both getAdIconView and getIconImageUrl are returned, prefer getAdIconView ; render only one of them
View getAdMediaView(Object.. object) Gets the ad main-image rendering container (only exists on some ad platforms); it may be a static image or a video. When both getAdMediaView and getMainImageUrl are returned, prefer getAdMediaView ; render only one of them
String getMainImageUrl Gets the main image URL. When both getAdMediaView and getMainImageUrl are returned, prefer getAdMediaView ; render only one of them
String getTitle() Gets the ad title. Must be rendered when returned
String getDescriptionText() Gets the ad description. Must be rendered when returned
String getCallToActionText() Gets the ad CTA button text. Must be rendered when returned
String getAdFrom() Gets the ad source. The Nend ad platform must render this information
String getAdChoiceIconUrl() Gets the ad choice icon URL. Choose and render one of getAdLogo, getAdLogoView ; it may not always exist
Bitmap getAdLogo() Gets the AdLogo Bitmap. Choose and render one of getAdChoiceIconUrl, getAdLogoView ; it may not always exist
View getAdLogoView() Gets the AdLogoView. Choose and render one of getAdChoiceIconUrl, getAdLogo ; it may not always exist
List getImageUrlList() Gets the list of image URLs
Double getStarRating() Gets the ad rating
String getAdType() Gets the ad type (video, image):
CustomNativeAd.NativeAdConst.VIDEO_TYPE: video type
CustomNativeAd.NativeAdConst.IMAGE_TYPE: image type
CustomNativeAd.NativeAdConst.UNKNOWN_TYPE: unknown ad type (both unsupported platforms and cases where it cannot be obtained are unknown ad types)
int getNativeAdInteractionType() Gets the ad interaction type
NativeAdInteractionType.APP_DOWNLOAD_TYPE: download ad;
NativeAdInteractionType.H5_TYPE: web page ad
NativeAdInteractionType.DEEPLINK_TYPE: app-redirect ad
NativeAdInteractionType.UNKNOW: unknown ad type
int getNativeType() Gets the ad type CustomNativeAd.NativeType.FEED: feed ad (Native Ad) CustomNativeAd.NativeType.PATCH: patch ad
double getVideoDuration() Gets the total video duration (double type, unit: seconds)
int getMainImageWidth() Gets the main image width; unsupported platforms return -1
int getMainImageHeight() Gets the main image height; unsupported platforms return -1
int getVideoWidth() Gets the video width; unsupported platforms return -1
int getVideoHeight() Gets the video height; unsupported platforms return -1
String getAdvertiserName() Gets the advertiser name
String getDomain() Returns the advertiser domain. Supported only by yandex
String getWarning() Returns the warning text. Supported only by yandex

● ATNativePrepareInfo

Used for Self-Rendering ads to bind self-rendering elements and click events

Method Description
void setParentView(View parentView) Binds the parent View
void setTitleView(View titleView) Binds the title View ; binding recommended
void setIconView(View iconView) Binds the app icon View ; binding recommended
void setMainImageView(View mainImageView) Binds the main image View ; binding recommended
void setDescView(View descView) Binds the description View ; binding recommended
void setCtaView(View ctaView) Binds the CTA button View ; binding recommended
void setChoiceViewLayoutParams(FrameLayout.LayoutParams choiceViewLayoutParams) Sets the ad choice size and position
void setClickViewList(List clickViewList) Binds the collection of clickable Views
void setCloseView(View closeView) Binds the close button
void setAdFromView(View adFromView) Binds the ad source View ; binding recommended (required for yandex)
void setAdLogoView(View adLogoView) Binds the AdLogo View
void setDomainView(View domainView) Binds the domainView (required for yandex)
void setWarningView(View warningView) Binds the warningView (required for yandex)

● ATNativePrepareExInfo

Inherits from ATNativePrepareInfo. The methods are the same as ATNativePrepareInfo; the additional methods are described below

Method Description
void setCreativeClickViewList(List creativeClickViewList) Binds the collection of click Views for direct-download ads
void setPermissionClickViewList(List permissionClickViewList) Binds the collection of click Views for viewing permissions
void setPrivacyClickViewList(List privacyClickViewList) Binds the collection of click Views for viewing the privacy policy
void setAppInfoClickViewList(List appInfoClickViewList) Binds the collection of click Views for viewing product info

● TUNative

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

Method Description
TUNative(Context context, String placementId, TUNativeNetworkListener listener) Native Ad initialization method
context: the Context; we recommend passing an Activity
placementId: ad ID, obtained by creating a Native Ad Placement in the TopOn dashboard
listener: ad placement event callback listener
void setLocalExtra(Map map) Sets custom information before loading or when displaying the ad
void setAdListener(TUNativeNetworkListener listener) Sets the placement-level ad listener callback
listener: ad placement event callback interface class
void makeAdRequest() Initiates ad loading
NativeAd getNativeAd() Gets the ad object, used to display the ad
Return value: the ad object
NativeAd getNativeAd(TUShowConfig showConfig) (Added in v6.3.10) Gets an ad that has finished loading (we recommend performing a non-null check after getting it) and sets the ad scenario for the subsequent ad display. showConfig: additional parameters can be passed at display time, as follows:
1.TUShowConfig#showCustomExt(String showCustomExt) : a custom parameter can be passed at display time; passing this parameter will return it through TUAdInfo#getShowCustomExt()
2.TUShowConfig#scenarioId(String scenarioId) : an Ad Scenario ID can be passed
void entryAdScenario(String placementId, String scenarioId) Enters the business scenario to track the current ad placement's cache status. For detailed 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), the scenario parameter can be created in the dashboard

● TUNativeNetworkListener

Placement-level Ad Event Callbacks

Method Description
void onNativeAdLoaded() Ad load success callback
void onNativeAdLoadFail(AdError error) Ad load failure callback; you can get all error information through AdError.getFullErrorInfo()
error: error information
Note: Do not perform the ad loading method for retries in this callback; otherwise it will cause many useless requests and may cause the app to lag

● NativeAd

The Native Ad object, used to display the ad

Method Description
void setNativeEventListener(TUNativeEventListener listener) Sets the ad display-related event listener callback
listener: ad display event listener
boolean isNativeExpress() Whether it is a template-rendering ad. Return value:
true = template ad
false = Self-Rendering ad
TUNativeMaterial getAdMaterial() Gets the ad material object, supported only for Self-Rendering ads
Return value: the ad material object
void renderAdContainer(TUNativeAdView view, View selfRenderView) For ad rendering.
view: the ad container provided by TopOn; passing null will cause the display to fail
selfRenderView: the developer's custom View. When isNativeExpress() returns false, selfRenderView must be the developer's custom View; when it returns true, null can be passed
void prepare(TUNativeAdView view, TUNativePrepareInfo nativePrepareInfo) For configuring ad click events, binding self-rendering elements, etc.
view: the ad container provided by TopOn; passing null will cause the display to fail
nativePrepareInfo: used for Self-Rendering ads to bind self-rendering elements and click events, etc.; for template ads null can be passed
Note: The prepare method must be called after the renderAdContainer method, whether Self-Rendering or template rendering
void destory() Destroys the ad; after calling it, the NativeAd object can no longer be used to render or display ads

● TUNativeEventListener

Ad display-related event listener callback

Method Description
void onAdImpressed(TUNativeAdView view, TUAdInfo adInfo) Ad display success callback
view: the ad container
void onAdClicked(TUNativeAdView view, TUAdInfo adInfo) Ad click callback view: the ad container
adInfo: the ad information object
void onAdVideoStart(TUNativeAdView view) Video ad playback start callback
view: the ad container
void onAdVideoProgress(TUNativeAdView view, int progress) Video ad playback progress callback
view: the ad container
progress: playback progress
void onAdVideoEnd(TUNativeAdView view) Video ad playback end callback
view: the ad container

● TUNativeMaterial

The ad material object returned by Self-Rendering ads ( All returned materials below may be null, because some ad platforms may not have all material information )

Method Description
String getIconImageUrl() Gets the ad icon URL. When both getAdIconView and getIconImageUrl are returned, prefer getAdIconView ; render only one of them
View getAdIconView() Gets the ad IconView. When both getAdIconView and getIconImageUrl are returned, prefer getAdIconView ; render only one of them
View getAdMediaView(Object.. object) Gets the ad main-image rendering container (only exists on some ad platforms); it may be a static image or a video. When both getAdMediaView and getMainImageUrl are returned, prefer getAdMediaView ; render only one of them
String getMainImageUrl Gets the main image URL. When both getAdMediaView and getMainImageUrl are returned, prefer getAdMediaView ; render only one of them
String getTitle() Gets the ad title. Must be rendered when returned
String getDescriptionText() Gets the ad description. Must be rendered when returned
String getCallToActionText() Gets the ad CTA button text. Must be rendered when returned
String getAdFrom() Gets the ad source. The Nend ad platform must render this information
String getAdChoiceIconUrl() Gets the ad choice icon URL. Choose and render one of getAdLogo, getAdLogoView ; it may not always exist
Bitmap getAdLogo() Gets the AdLogo Bitmap. Choose and render one of getAdChoiceIconUrl, getAdLogoView ; it may not always exist
View getAdLogoView() Gets the AdLogoView. Choose and render one of getAdChoiceIconUrl, getAdLogo ; it may not always exist
List getImageUrlList() Gets the list of image URLs
Double getStarRating() Gets the ad rating
String getAdType() Gets the ad type (video, image):
CustomNativeAd.NativeAdConst.VIDEO_TYPE: video type
CustomNativeAd.NativeAdConst.IMAGE_TYPE: image type
CustomNativeAd.NativeAdConst.UNKNOWN_TYPE: unknown ad type (both unsupported platforms and cases where it cannot be obtained are unknown ad types)
int getNativeAdInteractionType() Gets the ad interaction type
NativeAdInteractionType.APP_DOWNLOAD_TYPE: download ad;
NativeAdInteractionType.H5_TYPE: web page ad
NativeAdInteractionType.DEEPLINK_TYPE: app-redirect ad
NativeAdInteractionType.UNKNOW: unknown ad type
int getNativeType() Gets the ad type CustomNativeAd.NativeType.FEED: feed ad (Native Ad) CustomNativeAd.NativeType.PATCH: patch ad
double getVideoDuration() Gets the total video duration (double type, unit: seconds)
int getMainImageWidth() Gets the main image width; unsupported platforms return -1
int getMainImageHeight() Gets the main image height; unsupported platforms return -1
int getVideoWidth() Gets the video width; unsupported platforms return -1
int getVideoHeight() Gets the video height; unsupported platforms return -1
String getAdvertiserName() Gets the advertiser name
String getDomain() Returns the advertiser domain. Supported only by yandex
String getWarning() Returns the warning text. Supported only by yandex

● TUNativePrepareInfo

Used for Self-Rendering ads to bind self-rendering elements and click events

Method Description
void setParentView(View parentView) Binds the parent View
void setTitleView(View titleView) Binds the title View ; binding recommended
void setIconView(View iconView) Binds the app icon View ; binding recommended
void setMainImageView(View mainImageView) Binds the main image View ; binding recommended
void setDescView(View descView) Binds the description View ; binding recommended
void setCtaView(View ctaView) Binds the CTA button View ; binding recommended
void setChoiceViewLayoutParams(FrameLayout.LayoutParams choiceViewLayoutParams) Sets the ad choice size and position
void setClickViewList(List clickViewList) Binds the collection of clickable Views
void setCloseView(View closeView) Binds the close button
void setAdFromView(View adFromView) Binds the ad source View ; binding recommended (required for yandex)
void setAdLogoView(View adLogoView) Binds the AdLogo View
void setDomainView(View domainView) Binds the domainView (required for yandex)
void setWarningView(View warningView) Binds the warningView (required for yandex)

● TUNativePrepareExInfo

Inherits from TUNativePrepareInfo. The methods are the same as TUNativePrepareInfo; the additional methods are described below

Method Description
void setCreativeClickViewList(List creativeClickViewList) Binds the collection of click Views for direct-download ads
void setPermissionClickViewList(List permissionClickViewList) Binds the collection of click Views for viewing permissions
void setPrivacyClickViewList(List privacyClickViewList) Binds the collection of click Views for viewing the privacy policy
void setAppInfoClickViewList(List appInfoClickViewList) Binds the collection of click Views for viewing product info

8. Advanced Settings

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


9. Integration Reference

Sample Code: NativeAdActivity.java in the Demo


10. Ad Network Specific Configuration Instructions

● Huawei Native Ad Close Button and i Icon

Note: If your app needs to be published on the Huawei AppGallery, please do not use the third option.

(1) Show the close button and do not show the i icon (the close button position can be specified)

java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiATConst.CUSTOM_DISLIKE, false);
// Set the close button position
localExtra.put(ATAdConst.KEY.AD_CHOICES_PLACEMENT, ATAdConst.AD_CHOICES_PLACEMENT_TOP_RIGHT);
mATNative.setLocalExtra(localExtra);

mATNative.makeAdRequest();

(2) Show the i icon, do not show the close button (the i icon position can be specified)

java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiATConst.CUSTOM_DISLIKE, true);
// Set the i icon position
localExtra.put(ATAdConst.KEY.AD_CHOICES_PLACEMENT, ATAdConst.AD_CHOICES_PLACEMENT_BOTTOM_RIGHT);
mATNative.setLocalExtra(localExtra);

mATNative.makeAdRequest();

(3) Show neither the i icon nor the close button

java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiATConst.CUSTOM_DISLIKE, true);
localExtra.put(ATAdConst.KEY.AD_CHOICES_PLACEMENT, ATAdConst.AD_CHOICES_PLACEMENT_INVISIBLE);
mATNative.setLocalExtra(localExtra);

mATNative.makeAdRequest();
java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiTUConst.CUSTOM_DISLIKE, false);
// Set the close button position
localExtra.put(TUAdConst.KEY.AD_CHOICES_PLACEMENT, TUAdConst.AD_CHOICES_PLACEMENT_TOP_RIGHT);
mTUAdNative.setLocalExtra(localExtra);

mTUAdNative.makeAdRequest();

(2) Show the i icon, do not show the close button (the i icon position can be specified)

java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiTUConst.CUSTOM_DISLIKE, true);
// Set the i icon position
localExtra.put(TUAdConst.KEY.AD_CHOICES_PLACEMENT, TUAdConst.AD_CHOICES_PLACEMENT_BOTTOM_RIGHT);
mTUAdNative.setLocalExtra(localExtra);

mTUAdNative.makeAdRequest();

(3) Show neither the i icon nor the close button

java Copy
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(HuaweiTUConst.CUSTOM_DISLIKE, true);
localExtra.put(TUAdConst.KEY.AD_CHOICES_PLACEMENT, TUAdConst.AD_CHOICES_PLACEMENT_INVISIBLE);
mTUAdNative.setLocalExtra(localExtra);

mTUAdNative.makeAdRequest();
Previous
Customized banner ads
Next
Notes for Native Self-Rendering Ads
Last modified: 2026-07-08Powered by