Skip to main content

Native Ads

Precautions#

  • It is forbidden to execute the method of ad loading in the onAdLoadFailed callback, otherwise it will cause an infinite loop.

  • It is forbidden to directly execute the method of ad display in the onAdLoaded callback. The SDK has the function of automatic replenishment of expired ads. If the display is executed in the onAdLoaded callback, the developer will not be able to accurately control the timing of ad display.

  • According to the supported advertising platforms, native ads are divided into template type and self-rendering type.

    • For template type ads, the third-party advertising platform will directly return a complete view, and the developer only needs to call it normally to display it.
    • For self-rendering type ads, the third-party advertising platform returns the advertising material and displays it using the layout passed in by the developer. The type selection of the third-party background needs to be consistent with the TP background, otherwise the request will fail.

  • Developers can refer to the native.dart integration in the Demo

Integration steps#

1、Request Ads#

Map customMap = {};
Map localParams = {};
Map extraMap = TPNativeManager.createNativeExtraMap(
templateHeight: 320,
templateWidth: 340,
customMap: customMap,
localParams: localParams);
TPNativeManager.loadNativeAd("your unitId", extraMap: extraMap);

Parameter Description

unitId：The unitId created in the TradPlus backend#
  • Developers must fill in the information correctly. For example, if there are spaces before and after the unitId setting, the ad request will fail because the configuration cannot be pulled.
extraMap：Additional parameters#
  • customMap：Set Traffic Grouping Related attribute parameters
  • localParams：Set local parameters. Parameters that need to be set for individual advertising platforms.
  • templateHeight and templateWidth: The width and height of the ad display must be passed in before the native template type requests an ad. If not passed, the SDK will use the width and height values recommended by the third-party ad platform.

2、Check if ads are available#

  • Developers call this method after listening to the onAdLoaded callback.
  • It is recommended that developers call this API to determine whether there are available ads before displaying ads, and then call the show method if there are ads.
  • true means there are available ads, false means there are no available ads for the time being
  • When calling nativeAdReady and returns false, the sdk will request ads again, and the developer does not need to call the load method again.
bool isReady = await TPNativeManager.nativeAdReady("unitId");

3、Enter the Ad scene#

TPNativeManager.entryNativeAdScenario("unitId", sceneId: "sceneId");

Parameter Description

sceneId ：ad scene ID#
  • Developers can create it in the TradPlus backend at the following location: Application Management - ad Scene.
  • For details on how to call, please refer to Description of the timing and purpose of calling advertising scenes。
  • When entering the advertising scene, pass in the sceneId. When displaying the advertisement, you also need to pass in the sceneId, otherwise it will affect the statistics.

4、Display ads#

  • When loaded is complete and the call to nativeAdReady returns true, the ad is displayed.
  • Developers need to create their own widgets to display ads.

Method 1: Use layout files to display ads#

return TPNativeViewWidget("unitId", width, height,
className: "layout",sceneId: "sceneId");

TPNativeViewWidget Attribute Description

  • width、height：Set Width and Height
  • className：The layout files introduced in the above document prohibit developers from modifying the android🆔 resource ID in the layout files, which will cause the self-rendering type ads to fail to find the corresponding ID and display;
  • sceneId ：ad scene ID
（1）Android platform layout import#

The default layout is provided in the layout file. After downloading the compressed package and unzipping it, import the native_ad_list_item.xml in the res folder into the directory as shown in the figure:

如图：

（2）iOS platform layout import#

You can get the default layout file from the res directory in the compressed package of the SDK downloaded from the Packaging Platform page

Place TPNativeTemplate.xib in tradplus_sdk/ios/Assets/

Place TPNativeTemplate.h, TPNativeTemplate.m in tradplus_sdk/ios/Classes/

In this way, you can import the layout file into the Xcode project through pods and use it

Method 2: Create a layout to display ads using Flutter#

Using this method to display ads, there is no need to import the layout file provided by TradPlus

return TPNativeViewWidget(
"unitId",
width,
height,
sceneId: "sceneId",
extraMap: {
"parent": TPNativeManager.createNativeSubViewAttribute(320, 320,
backgroundColorStr: "#FFFFFF"),
"appIcon": TPNativeManager.createNativeSubViewAttribute(50, 50,
x: 10, y: 10),
"mainTitle": TPNativeManager.createNativeSubViewAttribute(
320 - 190, 20,
x: 70, y: 40),
"desc": TPNativeManager.createNativeSubViewAttribute(320 - 190, 20,
x: 70, y: 70),
"cta": TPNativeManager.createNativeSubViewAttribute(100, 50,
x: 320 - 110, y: 40, backgroundColorStr: "#AAF7DC6F"),
"mainImage": TPNativeManager.createNativeSubViewAttribute(
320, 320 * 0.6,
x: 0, y: 100),
"adLogo": TPNativeManager.createNativeSubViewAttribute(20, 20,
x: 320 - 30, y: 10)
},
);

TPNativeViewWidget Attribute Description

  • width、height：Set Width and Height

  • className：The layout files introduced in the above document prohibit developers from modifying the android🆔 resource ID in the layout files, which will cause the self-rendering type ads to fail to find the corresponding ID and display;

  • sceneId ：ad scene ID

  • extraMap : Custom Map Parameters

    • width,height：The width and height of the element
    • backgroundColorStr：Background Color
    • textColorStr：Font Color
    • textSize：Font size
    • x,y:Internal child control coordinates

5、Listening callback#

Parameter Description

Basic callback#

listener = TPNativeAdListener(
onAdLoaded: (adUnitId, adInfo) {
// Ad loading successful
// You cannot call the show method to display ads in this callback
// V1.1.2 callback mechanism optimization, developers will call load once to get a corresponding loaded callback, no call will result in no callback
},
onAdLoadFailed: (adUnitId, error) {
// Ad loading failed
// You cannot call the load method again to request an ad in this callback, which will result in multiple invalid requests
},
onAdImpression: (adUnitId, adInfo) {
// Ad display
},
onAdShowFailed: (adUnitId, adInfo, error) {
// Ad display failed (partial ad support)
},
onAdClicked: (adUnitId, adInfo) {
//Ad clicked
},
onAdClosed: (adUnitId, adInfo) {
//Ad closed
},
oneLayerLoadFailed: (adUnitId, adInfo, error) {
// Ad source loading failed
// Do not call the load method again to request ads in this callback, which will result in multiple invalid requests
// During testing, developers can monitor this callback and obtain the reason for the failure to load each ad platform through error
}
);
TPNativeManager.setNativeAdListener(listener!);

other callback(optional)#

...
onAdStartLoad: (adUnitId, adInfo) {
// The callback returned each time the load method is called
},
onBiddingStart: (adUnitId, adInfo) {
// Bidding starts loading
},
onBiddingEnd: (adUnitId, adInfo, error) {
// Bidding loading is finished
// Configure bidding ad source to listen
// During testing, get the reason why bidding loading failed through error
}
oneLayerStartLoad: (adUnitId, adInfo) {
//Callback triggered before each layer of waterfall initiates a request to the third-party advertising source
},
oneLayerLoaded: (adUnitId, adInfo) {
// Configure multiple ad sources in the background, and each ad source will be called back once after loading successfully
},
onVideoPlayStart: (adUnitId, adInfo) {
// video start（supported by some ad sources）
},
onVideoPlayEnd: (adUnitId, adInfo) {
// video end（supported by some ad sources）
},
onAdAllLoaded: (adUnitId, isSuccess) {
// Status of the ad slot
// isSuccess returns true, indicating that an ad source has been successfully loaded for this request
// isSuccess returns false, indicating that all ad sources under the ad slot adUnitId have failed to load for this request
}，
onAdIsLoading: (adUnitId) {
// New in V1.0.5
// If this callback is received after calling load, it means that the ad slot is still in the loading state and cannot trigger a new round of ad loading.
}
...

Download Kuaishou, ByteDance support (optional) (only supported by Android)#

...
onDownloadStart: (adUnitId, totalBytes, currBytes, fileName, appName) {
// Start download callback
// totalBytes: total file size (unit: bytes)
// currBytes: currently downloaded size (unit: bytes)
// fileName: file name
// appName: application name corresponding to the file
},
onDownloadUpdate: (adUnitId, totalBytes, currBytes, fileName, appName, progress) {
// Download progress update callback
// progress: download progress
},
onDownloadPause: (adUnitId, totalBytes, currBytes, fileName, appName) {
// Pause download callback
},
onDownloadFinish: (adUnitId, totalBytes, currBytes, fileName, appName) {
// Download completed callback
},
onDownloadFail: (adUnitId, totalBytes, currBytes, fileName, appName) {
// Download failed callback
},
onInstall: (adUnitId, totalBytes, currBytes, fileName, appName) {
//Apk installation completed callback
}
...