1. Rendering Mode

● App Self-Rendering: the rendering mode in which developers assemble the ad assets into an ad on their own. Note: The type selected on the network dashboard must be consistent with that on the TopOn dashboard. For more information, you can refer to Notes for Native Self-Rendering Ad

● Template Rendering: the rendering mode in which the network returns a pre-rendered view, and developers need to simply place this view into a container to display the ad.

⚠️Note:

You can view the width-to-height ratio of template ads on the network dashboard. Please use this ratio when loading and displaying ads in your code.

The width and height of ATNativeAdView must be consistent with the width and height associated with ATAdConst.KEY.AD_WIDTH and ATAdConst.KEY.AD_HEIGHT, respectively.

2. Load a Native Ad

💡Please call this function in advance to reduce user waiting time.

ATNative atNative = new ATNative(context, "your placement id", new ATNativeNetworkListener() {
    @Override
    public void onNativeAdLoaded() {}
    
    @Override
    public void onNativeAdLoadFail(AdError adError) {
        //Note: Do not call load() here, as it may lead to an ANR error
    }
});
//load ad
atNative.makeAdRequest();

3. Show a Native Ad

//To render native ad, you need to create a container that can be defined in the XML layout
// for reference, see the Demo at https://github.com/toponteam/TPN-Android-Demo
ATNativeAdView mATNativeAdView = findViewById(R.id.native_ad_view);
//A container with a custom layout 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 use ATNative#makeAdRequest() to preload the ad
if (mNativeAd != null) {
    mNativeAd.setNativeEventListener(new ATNativeEventListener() {
        @Override
        public void onAdImpressed(ATNativeAdView view, ATAdInfo atAdInfo) {}
        
        @Override
        public void onAdClicked(ATNativeAdView view, ATAdInfo atAdInfo) {}
        
        @Override
        public void onAdVideoStart(ATNativeAdView view) {}
        
        @Override
        public void onAdVideoEnd(ATNativeAdView view) {}
        
        @Override
        public void onAdVideoProgress(ATNativeAdView view, int progress) {}
    });
    if (mNativeAd.isNativeExpress()) {
        // TopOn Template Rendering
        mNativeAd.renderAdContainer(mATNativeAdView, null);
        mNativeAd.prepare(mATNativeAdView, null);
    } else {
        //App Self-Rendering
        ATNativePrepareInfo nativePrepareInfo = new ATNativePrepareInfo();
        //The function for binding materials in the self-rendering approach is bindSelfRenderView()
        //for details, please 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);
    }
}

4. Ad Scenario Statistics

Track the scene arrival rates, which are presented in the TopOn dashboard under Report -> Funnel Report -> Scenario.

First, call entryAdScenario()

Then, call getNativeAd(ATShowConfig showConfig)

Finally, display the ad

void entryAdScenario(String placementId, String scenarioId) Enter the business scenario to track the current cache status of the ad placement. For specific usage, refer to the ad scenarios.
placementId: ad placement id, you can refer to here
scenarioId: ad scenario id (optional; passing null will record statistics under the default scenario)

NativeAd getNativeAd(ATShowConfig showConfig) (Added in v6.3.10) Retrieve the loaded ad object (it is recommended to perform a non-null check) and set its ad scenario ID.
showConfig: extra parameters that can be passed in at the time of display include:
1. ATShowConfig#showCustomExt(String showCustomExt): you can pass in custom parameters for display, which will be returned through ATAdInfo#getShowCustomExt().
2. ATShowConfig#scenarioId(String scenarioId): you can pass in the ad scenario ID.

ATNative.entryAdScenario("your placement id", "your scenario id");
......
ATShowConfig.Builder builder = new ATShowConfig.Builder();
builder.scenarioId("your scenario id");
builder.showCustomExt("your custom data");
//Note: Please call this function before displaying the ad
mATNative.getNativeAd(builder.build());

5. About Destroy

💡Tips

When you no longer need to display native ads, please remove the related views of the native ad from the layout and call NativeAd#destroy() to destroy the current ad resources.
@Override
protected void onDestroy() {
    super.onDestroy();
    if (mNativeAd != null) {
        mNativeAd.destory();
    }
    if (mATNative != null) {
        mATNative.setAdListener(null);
        mATNative.setAdSourceStatusListener(null);
        mATNative.setAdMultipleLoadedListener(null);
    }
}

6. Close button (optional)

(1) You can bind the close button by setting it in ATNativePrepareInfo by callingATNativePrepareInfo#setCloseView().

Note: Please bind the close button before calling prepare()

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

//The function for binding materials in the self-rendering approach is bindSelfRenderView()
//for details, please 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 close button
    View closeView = selfRenderView.findViewById(R.id.native_ad_close);
    ...
    nativePrepareInfo.setCloseView(closeView);
    ...
}

(2) Set the listener for the close button.

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

7. Advanced

Preset strategy : By configuring preset strategies, you can improve the ad loading performance during the app's initial cold start.

8. Note

● Huawei native ads' close button and 'i' icon

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

(1) Display the close button, but do not display the 'i' icon (you can specify the position of the close button).

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

mATNative.makeAdRequest();

(2) Display the 'i' icon, do not display the close button (you can specify the position of the 'i' icon).

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

mATNative.makeAdRequest();

(3) Do not display the 'i' icon or the close button.

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();

AD Formats