标准原生
一.集成建议
主要介绍在Android项目中如何集成 TradPlus SDK的标准原生广告：
- 原生广告可以由开发者控制大小，尽可能融入到app的内容中去，从而提升广告的点击和转化。
- 信息流是标准原生的一种使用场景，不是一种广告类型。就是在listview或者recyclerview中展示native广告（具体要根据开发者的场景来做调试）。这种场景下开发者可能会有一次请求多个广告的需求。可参考NativeSlot Demo进行开发集成。
- 原生广告分自渲染和模板渲染：
| 类型 | 说明 |
|---|---|
| 自渲染 | 三方广告平台返回广告素材由开发者来拼接成的类型。三方后台的类型选择需要和TP后台一致，否则会请求失败。 |
| 模板渲染 | 三方广告平台返回渲染好的view，开发者直接添加到一个容器就可以展示出来。 |
注意事项
Meta (FaceBook)
- (1)元素齐全：接入Meta (FaceBook)原生广告必须有以下元素,缺少这些元素可能会导致不计入展示。更多了解，请看Audience Network 原生广告介绍。
- (2)图标(角标)：如图4的位置是Meta的角标,开发者自测过程中请注意角标的正常显示，不能有遮挡。
请求和展示
- 不建议在
oneLayerLoadFailed和onAdLoadFailed回调中执行广告加载的方法。对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。 - 【V9.9.0.1以下版本】 不建议在
onAdLoaded回调中直接执行广告展示的方法：- SDK有广告过期自动补充和自动加载功能，加载成功后会回调
onAdLoaded onAdLoaded回调中直接showAd()，会导致过期补充或自动加载成功后弹出广告影响用户体验- 建议：开发者记录
onAdLoaded状态，在需要展示广告的地方，先判断isReady()返回true，再展示广告
- SDK有广告过期自动补充和自动加载功能，加载成功后会回调
- 【V9.9.0.1 + 】优化回调机制，调用一次
loadAd()才会收到一次loaded回调。- 开发者可以直接在
onAdLoaded回调中执行广告展示
- 开发者可以直接在
二、TPNative API说明
1、创建广告位对象
| 方法 | 说明 |
|---|---|
| TPNative(Activity activity, String adUnitId) | 仅调用一次。 adUnitId是在TP平台创建的广告位ID。 |
2、加载、展示以及销毁广告
| 方法 | 说明 |
|---|---|
| loadAd() | 请求广告 |
| isReady() | 检测是否有可用广告。 V8.6.0.1新增API。 |
| showAd(ViewGroup adContainer, int layoutId) | 展示广告（方法一）—— 自渲染 & 模版 参数1 adContainer: 传空容器会导致展示失败。 参数2 layoutId 说明: (1)开发者可以从自动打包平台下载的layout文件夹中获取布局文件; (3)不清楚自渲染和模版的区别可看上文介绍; (2)将三方返回的自渲染元素的拼接好的布局，模版类型会直接展示; (4)禁止开发者修改布局文件中的 android:id: 资源ID，会导致自渲染广告的元素无法找到对应id而展示失败;(5)开发者可以调整元素位置； (6)禁止开发者删除 ad_choices等元素，缺少元素可能会导致某些广告平台不计入展示，详细了解请看上文集成建议中注意事项。TP提供的 布局文件中 tp_ad_choices_container 为Meta(FaceBook)和MTG的角标的容器；tp_native_ad_choice则是其他广告平台的角标Id，均不能删除。V6.9.1+版本优化 android:id: 资源ID,开发者要更新tp_native_ad_list_item.xml文件，如果是自定义模版，也需要更新id。 (7)每次从缓存中拿出一个新的广告show出来，一次loaded对应一次show。 |
| showAd(ViewGroup adContainer, int layoutId, String sceneId) | 展示广告并设置场景ID（方法二）—— 自渲染 & 模版 需和进入广告场景方法一起使用。 每次从缓存中拿出一个新的广告show出来，一次loaded对应一次show。 |
| showAd(ViewGroup adContainer, TPNativeAdRender adRender, String adSceneId) | 自定义渲染方式展示广告（方法三）—— 自渲染 开发者要自己渲染三方返回的元素，并且需要在loaded广告后调用。TPNativeAdRender的使用需要参考Demo。 仅自渲染类型支持。 |
| entryAdScenario(String sceneId) | 进入广告场景 需和（方法二）一起使用。 广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数，所以请在准确的位置调用。 |
| onDestroy() | 释放资源。 |
- 参数说明
| 参数 | 说明 |
|---|---|
| adUnitId | 广告位ID，TradPlus后台创建。应用管理——添加应用——添加广告位。 注意广告类型创建错误会导致广告展示失败，例如用标准原生的广告位去请求激励视频广告。 |
| sceneId | 广告场景ID，TradPlus后台创建。应用管理—— 广告场景。 具体如何使用，请看广告场景的调用时机和用途说明。 |
3、其他
| 方法 | 说明 |
|---|---|
| getNativeAd() | 获取TP的缓存对象。 (1)开发者如需要获取更多三方源的信息，可调用该API。 (2)获取后就会从TradPlus的缓存池中删除，所以不能重复调用，需要将get到的TPCustomNativeAd对象保存下来进行处理。 (3)可直接通过TPCustomNativeAd调用showAd()。 (4)获取TP缓存池中的一个广告，一次loaded可以get一个TPCustomNativeAd，不能重复调用，可能会空。 |
// 获取TP缓存对象
TPCustomNativeAd mCustomNativeAd;
TPNative tpNative = new TPNative(activity,"在TP平台创建的广告位ID");
tpNative.setAdListener(new NativeAdListener() {
@Override
public void onAdLoaded(TPAdInfo adInfo, TPBaseAd tpBaseAd) {
// 获取TP缓存缓存对象
mCustomNativeAd = tpNative.getNativeAd();
if(mCustomNativeAd.getCustomNetworkId() != null)
String id = mCustomNativeAd.getCustomNetworkId(); // 广告源的id
if(mCustomNativeAd.getCustomNetworkName() != null)
String name = mCustomNativeAd.getCustomNetworkName(); // 广告源的名称
...
mCustomNativeAd.showAd(adContainerView, R.layout.tp_native_ad_list_item, "");
}
....
});
- TPCustomNativeAd API 介绍
| 方法 | 类型 | 说明 |
|---|---|---|
| getCustomNetworkId() | String | 返回三方广告网络编号表。 |
| getCustomNetworkName() | String | 三方广告平台名称。 |
| getCustomNetworkObj() | Object | 返回三方的对象（如果没有特殊需求不建议使用） (1)TP将无法获取展示后包括展示、点击、广告关闭等监听回调; (2)原生模版和自渲染都能获取到； (3)原生自渲染类型的广告，开发者 可以直接获取这个对象拿到三方提供的素材。 |
| getNativeAdView() | TPNativeAdView | 获取TP包装过的对象。 (1)仅针对原生自渲染类型； (2)开发者可以获取TP包装过的所有素材。 |
| showAd(ViewGroup adContainer, int layoutId, String adSceneId) | - | 展示当前广告。 一个TPCustomNativeAd就是一个广告，同一个对象调用多次show，展示的是同一个广告。 |
| onDestroy() | - | 释放资源。 |
| setDislikeListener(TPNativeAdapter.onDislikeListener onDislikeListener) | - | dislike监听回调(可选 )。 仅百度模板、穿山甲模板、Sigomb、huawei支持； V9.7.10.1新增API。 |
- setDislikeListener 回调参数说明
| 方法 | 参数 | 说明 |
|---|---|---|
| onAdCloseButtonClick | String reason | 用户点击dislke关闭按钮； reason为返回用户选择不喜欢该广告的原因； 收到监听回调后，开发者要自行移除容器； |
4、监听回调
| 方法 | 说明 |
|---|---|
| setAdListener(NativeAdListener adListener) | 设置广告监听。 其中NativeAdListener是需要实现广告事件回调的接口类。 |
| setAllAdLoadListener(LoadAdEveryLayerListener everyLayerListener) | (可选) 设置单个源维度的监听回调。 V6.4.5新增API。其中LoadAdEveryLayerListener是需要实现广告事件回调的接口类。单个源维度是指TP端的一个广告位下配置多个广告源缓存，每 个源的回调。 |
| setDownloadListener(DownloadListener downloadListener) | 设置下载监听回调(可选 )。 快手、穿山甲等国内源支持。 V8.1.0.1新增API。 |
- 监听回调中的参数说明 V6.2.4新增API
| 参数 | 说明 |
|---|---|
| TPAdInfo | 广告位ID、三方广告平台、ecpm等信息，具体请参考回调信息说明。 |
| TPAdError | 广告请求失败、广告展示失败的错误码、错误信息，具体请参考错误码、错误信息说明。 |
- NativeAdListener（广告位维度）
| 方法 | 说明 |
|---|---|
| onAdClicked(TPAdInfo tpAdInfo) | 广告被点击。 |
| onAdImpression(TPAdInfo tpAdInfo) | 广告被展示。 |
| onAdClosed(TPAdInfo tpAdInfo) | 广告被关闭。 |
| onAdLoaded(TPAdInfo tpAdInfo, TPBaseAd tpBaseAd) | 广告加载成功。 V9.9.0.1优化回调机制，开发者主动调用一次load才会对应回调一次loaded,不调用不回调。 |
| onAdLoadFailed(TPAdError error) | 广告加载失败。 |
| onAdShowFailed(TPAdError error, TPAdInfo tpAdInfo) | 广告展示失败。 |
| onAdVideoStart(TPAdInfo tpAdInfo) | 视频播放开始。部分广告平台支持。 V8.1.0.1新增。 |
| onAdVideoEnd(TPAdInfo tpAdInfo) | 视频播放结束。部分广告平台支持。 V8.1.0.1新增。 |
- LoadAdEveryLayerListener（可选）（单个源维度）V6.4.5新 增API
| 方法 | 说明 |
|---|---|
| onAdAllLoaded(boolean isSuccess) | 广告位的状态。loadAd()完毕后用于判断是否有可用广告，true表明有可用广告，false表明没有可用广告。 |
| oneLayerLoadFailed(TPAdError adError, TPAdInfo adInfo) | 配置多个广告源缓存，当每个广告源加载失败后都会回调一次。 |
| oneLayerLoaded(TPAdInfo adInfo) | 配置多个广告源缓存，当每个广告源加载成功后都会回调一次。 |
| 请求广告后，广告开始加载。 V7.9.0 废弃。 | |
| oneLayerLoadStart(TPAdInfo tpAdInfo) | 每层waterfall 向三方广告源发起请求前，触发的回调。V7.9.0 新增。 |
| onAdStartLoad(String adUnitId) | 每次调用load方法时返回的回调。V7.9.0 新增。 |
| onBiddingStart(TPAdInfo tpAdInfo) | Bidding开始加载。 |
| onBiddingEnd(TPAdInfo tpAdInfo, TPAdError tpAdError) | Bidding加载完成。 V7.3.0新增回调参数TPAdError。 |
| onAdIsLoading(String adUnitId) | 调用load之后如果收到此回调，说明广告位仍处于加载状态，无法触发新的一轮广告加载。 V9.0.0新增回调。 |
- setDownloadListener（可选）（部分国内源支持）V8.1.0.1新增
| 方法 | 参数 | 说明 |
|---|---|---|
| onDownloadStart | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 开始下载回调。 TPAdInfo：广告的信息对象，具体请参考上文回调信息说明 totalBytes：文件总大小（单位：字节） currBytes：当前已下载的大小（ 单位：字节） fileName：文件名称 appName：文件对应的应用名称 |
| onDownloadUpdate | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName,int progress | 下载进度更新回调。 参数意义同上。 |
| onDownloadPause | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 暂停下载回调。 参数意义同上。 |
| onDownloadFinish | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 下载完成回调。 参数意义同上。 |
| onDownloadFail | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | 下载失败回调。 参数意义同上。 |
| onInstalled | TPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName | Apk安装完成回调。 参数意义同上。 |
三、示例代码
请参考Native Demo
TPNative tpNative = new TPNative(activity,"AdUnitId");
tpNative.entryAdScenario(sceneId);
tpNative.setAdListener(new NativeAdListener() {
@Override
public void onAdLoaded(TPAdInfo tpAdInfo, TPBaseAd tpBaseAd) {
// 广告加载成功
// 展示广告。需要在loaded回调后调用。参数2 layoutId布局,布局文件从Download的SDK文件中获取。参数3 不使用entryAdScenario()，可直接传空字符串。
tpNative.showAd(adContainer, R.layout.tp_native_ad_list_item, sceneId);
}
@Override
public void onAdClicked(TPAdInfo tpAdInfo) {}
@Override
public void onAdImpression(TPAdInfo tpAdInfo) {}
@Override
public void onAdShowFailed(TPAdError tpAdError, TPAdInfo tpAdInfo) {}
@Override
public void onAdLoadFailed(TPAdError tpAdError) {
Log.i(TAG, "onAdLoadFailed: 加载失败 , code : "+ tpAdError.getErrorCode() + ", msg :" + tpAdError.getErrorMsg());
}
@Override
public void onAdClosed(TPAdInfo tpAdInfo) {}
});
// 设置每层广告源回调监听(可选)
tpNative.setAllAdLoadListener(new LoadAdEveryLayerListener() {...});
......
tpNative.loadAd();