Native

1. Introduction to Native Ads

1.1 Integration Recommendations

Type	Description	Notes
Self-Rendering	The type where ad creatives returned by the third-party ad platform are assembled by the developer. The type selection in the third-party backend must match the TopOn dashboard, otherwise the request will fail.	Notes on Self-Rendering Native Ads
Template Rendering	The third-party ad platform returns a pre-rendered view, which the developer can directly add to a container for display.	- Template ads have their own aspect ratio, which can be viewed in the ad platform's backend. Try to select templates with the same or similar aspect ratios in the ad platform backend, and pass the width and height with that aspect ratio in the code to Load and display the ad for the best display results. - The width and height of ATNativeAdView must match the corresponding values of ATAdConst.KEY.AD_WIDTH and ATAdConst.KEY.AD_HEIGHT, otherwise incomplete display or overly small display may occur.

2. Different Integration Approaches

Integration Approach	Description
Self-Rendering Feed Ad	Developers can obtain all creatives of the ad through the API and customize their own UI layout for integration. See: Self-Rendering Feed Ad
Template Feed Ad	Developers can obtain a fully rendered ad View through the API and directly add it to a specified position for display. See: Template Feed Ad
Draw Feed Ad	Primarily suitable for full-screen flip video feed scenarios. See: Draw Feed Ad Integration

3. API Description

3.1 Initialization

• ATNative: The class for Native ad loading.

API	Description
ATNative(Context context, String nativeTakuPlacementID, ATNativeNetworkListener listener)	Native ad Initialization method, where nativeTakuPlacementID is obtained by creating a Native Ad Placement in the Taku dashboard.

• ATNativeNetworkListener: Listener for ad loading.

Method	Description
void onNativeAdLoaded()	Ad load success.
void onNativeAdLoadFail(AdError error)	Ad load failure. You can use AdError.getFullErrorInfo() to get the full error information. See AdError. Note: Do not execute the ad loading method for retry in this callback, as it will cause many unnecessary requests and may lead to app lag.

3.2 Ad Loading

• ATNative: The class for Native ad loading.

API	Description
void setLocalExtra(Map)	Set local parameters.
void makeAdRequest	Initiate a Native ad request.
NativeAd getNativeAd()	Get the ad that has finished loading. (It is recommended to always perform a non-null check after retrieval, as null may occur in some cases. It will be null when there is no ad cache.) Note: After calling this method, the SDK will remove one ad from the cache. If the NativeAd obtained by this method is not null, the developer must keep a reference to it for subsequent ad display; otherwise, the next call to this method may return null due to no ad cache.
NativeAd getNativeAd(ATShowConfig showConfig)	(Added in v6.3.10) Get the ad that has finished loading (it is recommended to always perform a non-null check after retrieval, as null may occur in some cases), and set the ad scenario for the ad to be displayed later. showConfig: Can pass extra parameters during display, as follows: 1. ATShowConfig#showCustomExt(String showCustomExt): Can pass custom parameters during display. The passed parameter will be returned via ATAdInfo#getShowCustomExt(). 2. ATShowConfig#scenarioId(String scenarioId): Can pass an ad scenario, same as getNativeAd(String scenario).
void entryAdScenario(String placementId, String scenarioId)	Enter a business scenario for current Ad Placement cache status statistics. scenario refers to the ad display scenario (optional, can be directly passed as null). Scenario parameters can be created from the dashboard. For usage, see Business Scenario Cache Status Statistics.
void entryAdScenario(String scenarioId)	(v6.5.80 and above) Enter a business scenario for current Ad Placement cache status statistics. scenario refers to the ad display scenario (optional, can be directly passed as null). Scenario parameters can be created from the dashboard. For usage, see Business Scenario Cache Status Statistics.
List checkValidAdCaches	Query the ATAdInfo objects of all cached information for the current Ad Placement. ATAdInfo: Ad information object, which can be used to distinguish ad platforms. It mainly contains the third-party mediation platform's ID information. See ATAdInfo Information.

3.3 Ad Display

NativeAd: The ad object obtained via getNativeAd.

Method	Description
isNativeExpress	Whether it is a template rendering type ad.
renderAdContainer(ATNativeAdView view, View selfRenderView)	Used for ad rendering. The view must use our provided ATNativeAdView. Note: When isNativeExpress() returns false (i.e., Self-Rendering), selfRenderView must pass the developer's custom View. When it returns true (Template Rendering), null can be passed.
prepare(ATNativeAdView view, ATNativePrepareInfo nativePrepareInfo)	Used for configuring ad click events, binding the close button for Self-Rendering, and controlling the display position and size of the ad badge, etc. Called after the renderAdContainer method. (By default, all views are clickable. If an ad badge exists, it will have a default display position and size.)

3.4 Other APIs

API	Description
getAdInfo	Get the current ad cache information as an ATAdInfo object. It mainly contains the third-party mediation platform's ID information. See ATAdInfo Information.
clear(ATNativeAdView view)	Remove the ad's binding to the view.
onResume	Called in Activity's onResume (mainly for video ads of certain ad platforms).
onPause	Called in Activity's onPause (mainly for video ads of certain ad platforms).
destory	Destroy the current ad object (the ad can no longer be displayed after this is executed).

3.5 Event Callbacks

• NativeAd: The ad object obtained via getNativeAd.

Method	Description
setNativeEventListener(ATNativeEventListener listener)	Set ad event listener. ATNativeEventListener is the interface class for ad events.
setDislikeCallbackListener(ATNativeDislikeListener listener)	Set ad close event callback.

• ATNativeDislikeListener: Ad Dislike listener class.

Method	Description
void onAdCloseButtonClick(ATNativeAdView view, ATAdInfo atAdInfo)	Callback when the close button is clicked. If you want to remove the ad, the developer needs to manually call the code to remove the Native View in this callback. ATAdInfo is the ad information object, which mainly contains the third-party mediation platform's ID information. See ATAdInfo Information.

• ATNativeEventListener: Ad event listener interface class.

Method	Description
void onAdImpressed(ATNativeAdView view, ATAdInfo atAdInfo)	Ad impression callback. ATAdInfo: Ad information object, which can be used to distinguish ad platforms. It mainly contains the third-party mediation platform's ID information. See ATAdInfo Information.
void onAdClicked(ATNativeAdView view, ATAdInfo atAdInfo)	Ad click callback. Parameter meaning is the same as above.
void onAdVideoStart(ATNativeAdView view)	Ad video playback start (only available for certain ad platforms).
void onAdVideoEnd(ATNativeAdView view)	Ad video playback end (only available for certain ad platforms).
void onAdVideoProgress(ATNativeAdView view, int progress)	Ad video playback progress (only available for certain ad platforms).

• ATNativeEventExListener: Ad event listener interface class, extends ATNativeEventListener.

Method	Description
void onAdActRewardSuccess(ATAdInfo atAdInfo)	(v6.6.21 and above) Baidu action reward support.
void onAdActReward(ATAdInfo atAdInfo,int remainActTime)	(v6.6.21 and above) Baidu action reward support. remainActTime is the remaining time when closed midway.