跳到主要内容

原生广告

一、注意事项​

  • 禁止在onAdLoadFailed回调中执行广告加载的方法，否则会引起死循环。
  • 禁止在onAdLoaded回调中直接执行广告展示的方法。SDK有广告过期自动补充功能。如果在onAdLoaded回调中执行展示，开发者会无法精准控制广告展示的时机。
  • 根据所支持的广告平台，原生广告分为模板类型和自渲染类型。
    • 模板类型的广告，三方广告平台会直接返回一个完整的view，开发者只需要正常调用就可以展示。
    • 自渲染类型的广告，三方广告平台是返回广告素材，使用开发者传入的布局进行展示。三方后台的类型选择需要和TP后台一致，否则会请求失败。
  • 开发者可以参考Demo中的native.dart集成

二、集成步骤​

1、请求广告​

//配置参数extraMap
Map customMap = {};//流量分组
Map localParams = {};//local自定义Map，仅Android支持
Map extraMap = TPNativeManager.createNativeExtraMap(
	templateHeight: 320,
	templateWidth: 340,
	customMap: customMap,
	localParams: localParams);

//请求广告
TPNativeManager.loadNativeAd("在TP平台创建的广告位ID", extraMap: extraMap);

参数说明

unitId：TradPlus后台创建的广告位ID​
  • 开发者需正确填入，例如：adUnitId设置前后有空格，均会导致广告因拉不到配置而请求失败。
extraMap：额外参数​
  • customMap：设置流量分组相关属性参数
  • localParams：设置本地参数。个别广告平台特殊需要设定的参数。
  • templateHeight和templateWidth：原生模板类型请求广告前传入广告展示的宽高，不传SDK内部会使用三方广告平台建议的宽高值。

2、检查是否有可用广告​

  • 开发者在监听到onAdLoaded回调后调用。
  • 建议开发者展示广告前，调用该API判断是否有可用广告,有广告再调用show方法
  • true表示有可用广告，false表示暂时无可用广告
  • 当调用nativeAdReady返回false时，sdk会重新请求广告，无需开发者再次调用load方法。
bool isReady = await TPNativeManager.nativeAdReady("unitId");

3、进入广告场景​

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

参数说明

sceneId ：广告场景ID​
  • 开发者可在在TradPlus后台创建，位置如下：应用管理--广告场景。
  • 具体如何调用，可以参考广告场景的调用时机和用途说明。
  • 进入广告场景时传入sceneId，展示广告时也需传入sceneId，否则会影响统计。

4、展示广告​

  • loaded结束并且调用nativeAdReady返回true时，进行广告展示。
  • 开发者需要自己创建Widget进行广告展示。

方法一：使用布局文件展示广告​

return TPNativeViewWidget("unitId", width, height,
     className: "布局文件",sceneId: "sceneId");

TPNativeViewWidget属性说明

  • width、height：设置宽高
  • className：上述文档介绍的布局文件，禁止开发者修改布局文件中的android🆔 资源ID，会导致自渲染类型广告的无法找到对应id而展示失败;
  • sceneId ：广告场景ID，上面文档已介绍。
（1）Android平台布局导入​

layout文件中提供了默认布局，下载压缩包解压后将res文件夹里的native_ad_list_item.xml导入到如图目录下：

如图：

（2）iOS平台布局导入​

您可以从 打包平台页面下载SDK的压缩包中res目录中获取到默认布局文件

将TPNativeTemplate.xib放置在 tradplus_sdk/ios/Assets/ 下

将TPNativeTemplate.h,TPNativeTemplate.m放置在 tradplus_sdk/ios/Classes/ 下

这样就可以通过pods将布局文件导入到xcode项目中并使用了

方法二：用Flutter方式创建布局展示广告​

使用这种方式展示广告，无需导入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属性说明

  • width、height：设置宽高

  • className：上述文档介绍的布局文件，禁止开发者修改布局文件中的android🆔 资源ID，会导致自渲染类型广告的无法找到对应id而展示失败;

  • sceneId ：广告场景ID，上面文档已介绍。

  • extraMap : 自定义Map参数

    • width,height：元素的宽高
    • backgroundColorStr：背景颜色
    • textColorStr：字体颜色
    • textSize：字体大小
    • x,y:内部子控件坐标

5、监听回调​

参数说明

基础回调监听​

listener = TPNativeAdListener(
  onAdLoaded: (adUnitId, adInfo) {
    // 广告加载成功
	// 不可以在此回调中，调用show方法展示广告
	// V1.1.2 回调机制优化，开发者主动调用一次load才会对应回调一次loaded，不调用不回调
  },
  onAdLoadFailed: (adUnitId, error) {
    // 广告加载失败
	// 不可以在此回调中，重新调用load方法请求广告，会导致多个无效请求
  },
  onAdImpression: (adUnitId, adInfo) {
    // 广告展示
  },
  onAdShowFailed: (adUnitId, adInfo, error) {
    // 广告展示失败（部分广告支持）
  },
  onAdClicked: (adUnitId, adInfo) {
    //广告被点击
  },
  onAdClosed: (adUnitId, adInfo) {
    //广告被关闭
  },
  oneLayerLoadFailed: (adUnitId, adInfo, error) {
    // 广告源加载失败
	// 不可以在此回调中，重新调用load方法请求广告，会导致多个无效请求
    // 测试时，开发者可监听该回调，通过error获取每个广告平台加载失败的原因
  }
);

//设置监听
TPNativeManager.setNativeAdListener(listener!);

广告源维度回调监听(可选)​

...
  //广告源维度监听回调（可选）
  onAdStartLoad: (adUnitId, adInfo) {
     // 每次调用load方法时返回的回调
  },
  onBiddingStart: (adUnitId, adInfo) {
    // Bidding开始加载
  },
  onBiddingEnd: (adUnitId, adInfo, error) {
    // Bidding加载结束
    // 配置Bidding广告源可监听
    // 测试时，通过error获取bidding加载失败的原因
  }
  oneLayerStartLoad: (adUnitId, adInfo) {
    // 每层waterfall向三方广告源发起请求前，触发的回调
  },
  oneLayerLoaded: (adUnitId, adInfo) {
    // 后台配置多个广告源，每个广告源加载成功后会都会回调一次
  },
  onVideoPlayStart: (adUnitId, adInfo) {
    // 视频播放开始（部分广告源支持）
  },
  onVideoPlayEnd: (adUnitId, adInfo) {
    // 视频播放结束（部分广告源支持）
  },
  onAdAllLoaded: (adUnitId, isSuccess) {
    // 广告位的状态
    // isSuccess 返回true，表示此次请求，有广告源加载成功
    // isSuccess 返回false，表示此次请求，广告位adUnitId下所有广告源加载失败
  }，
  onAdIsLoading: (adUnitId) {
    // V1.0.5 新增
    // 调用load之后如果收到此回调，说明广告位仍处于加载状态，无法触发新的一轮广告加载。
  }
...

下载监听 快手、穿山甲支持(可选)(仅Android支持)​

...
  onDownloadStart: (adUnitId, totalBytes, currBytes, fileName, appName) {
     // 开始下载回调
     // totalBytes：文件总大小（单位：字节）
     // currBytes：当前已下载的大小（单位：字节）
     // fileName：文件名称
     // appName：文件对应的应用名称
  },
  onDownloadUpdate: (adUnitId, totalBytes, currBytes, fileName, appName, progress) {
     // 下载进度更新回调
     // progress：下载进度
  },
  onDownloadPause: (adUnitId, totalBytes, currBytes, fileName, appName) {
     // 暂停下载回调
  },
  onDownloadFinish: (adUnitId, totalBytes, currBytes, fileName, appName) {
     // 下载完成回调
  },
  onDownloadFail: (adUnitId, totalBytes, currBytes, fileName, appName) {
     // 下载失败回调
  },
  onInstall: (adUnitId, totalBytes, currBytes, fileName, appName) {
     // Apk安装完成回调
  }
...