Skip to main content

横幅广告

一、集成建议​

主要介绍在Android项目中如何集成 TradPlus SDK的横幅广告：

  • banner广告的TPBanner本身是一个view，需要开发者创建后添加到指定位置
  • 广告onAdLoaded成功后，TradPlus SDK会自动的把广告内容填充到TPBanner中
  • 在TradPlus后台配置自动刷新功能，一次onAdLoaded后，间隔固定的时间SDK内部会自动触发下一次load并在onAdLoaded成功后替换内容。请参考 自动刷新功能使用注意事项集成。
  • 开发者调用 closeAutoshow()方法，TP SDK不会自动调用showAd()。需要开发者在监听到onAdLoaded回调后在展示广告的位置执行showAd()。

注意事项​

  • 不建议在oneLayerLoadFailed和onAdLoadFailed回调中执行广告加载的方法。对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。
  • 【V9.9.0.1以下版本】 不建议在onAdLoaded回调中直接执行广告展示的方法：
    • SDK有广告过期自动补充和自动加载功能，加载成功后会回调onAdLoaded
    • onAdLoaded回调中直接showAd()，会导致过期补充或自动加载成功后弹出广告影响用户体验
    • 建议：开发者记录onAdLoaded状态，在需要展示广告的地方，先判断isReady()返回true，再展示广告
  • 【V9.9.0.1 + 】优化回调机制，调用一次loadAd()才会收到一次loaded回调。
    • 开发者可以直接在onAdLoaded回调中执行广告展示
  • 建议展示容器使用FrameLayout；如果使用LinearLayout，在addView的同时需要设置layoutParams
  • 三方轮播（自动刷新）
    • 部分三方源支持轮播功能，如穿山甲、腾讯优量汇等。
    • TP已支持了自动刷新功能，三方轮播能代码控制的均属于关闭状态，有需要可以直接在TP后台设置。
    • Google Admob 支持折叠横幅，配置折叠横幅样式的横幅广告位，不支持设置自动刷新
  • Mintegral、IronSource平台存放banner素材的父容器必须给定高度，不能是wrap_content，不然会全屏展示
  • Yandex平台需要在请求广告前就添加tpBanner到展示容器中adContainer.addView(tpBanner);否则加载成功会无法展示
  • YSO Network平台不支持load和show分开使用，存放Banner素材的父容器必须给定高度，不然广告无法正常展示

二、TPBanner API说明​

2.1 创建广告位对象​

方法说明
TPBanner(Activity activity)仅初始化时调用一次。

2.2 加载、展示广告​

方法说明
closeAutoShow()关闭自动展示(可选)。V6.9.5新增API。
使用须知：
(1)必须在请求load()前调用；
(2)需要在展示广告的位置调用showAd()，否则广告加载成功后无法展示。
loadAd(String adUnitId)请求广告（方法一）
adUnitId是在TP平台创建的广告位ID。
loadAd(String adUnitId,String sceneId)请求广告并设置广告场景ID（方法二）
使用该方法必须调用entryAdScenario(sceneId)
entryAdScenario(String sceneId)进入广告场景(可选)
广告场景是用来统计进入广告场景的次数和进入场景后展示广告的次数，所以请在准确的位置调用。
isReady()检测是否有可用广告。
V8.6.0.1新增API。
setNativeAdRender(TPNativeAdRender nativeAdRender)自定义渲染的方式设置原生横幅(可选)。V8.7.0.1新增API
（1）8.7.0.1开始支持使用横幅广告位配置原生横幅类型，SDK内置默认布局样式，如果开发者需要自己定义布局样式，就需要使用此方法渲染。
（2）详细了解，见下文《如何使用横幅广告位配置原生横幅》部分介绍
showAd()展示广告(可选)
需要和closeAutoShow()一起调用。V6.9.5新增API。注意：Baidu的Banner不支持load()和show()分开调用。
showAd(String adSceneId)**展示广告并传入广告场景ID(可选)。**需要和closeAutoShow()一起调用。
V8.6.0.1新增API。
  • 参数说明
参数说明
adUnitId广告位ID，TradPlus后台创建。应用管理——添加应用——添加广告位。
注意广告类型创建错误会导致广告展示失败，例如用标准原生的广告位去请求激励视频广告。
sceneId广告场景ID，TradPlus后台创建。应用管理—— 广告场景。
具体如何使用，请看广告场景的调用时机和用途说明。

2.3 其他 API​

方法说明
setVisibility(View.GONE)加载广告成功之后，隐藏。(可选)需要在主线程调用。
setVisibility(View.VISIBLE)隐藏广告后，展示。(可选)需要在主线程调用。
setAutoDestroy(boolean destory)设置不自动释放。默认是true。在TPBanner被remove后会释放广告资源。如果特殊场景需要保存TPBanner继续使用，可以设置false。
isOpenAutoRefresh()判断是否开启自动刷新。(可选) V7.1.0.1新增API
onDestroy()释放广告。

2.4 监听回调​

方法说明
setAdListener(BannerAdListener adListener)设置广告监听回调，其中BannerAdListener是需要实现广告事件回调的接口类。
setAllAdLoadListener(LoadAdEveryLayerListener everyLayerListener)设置单个源维度的监听回调(可选)
V6.9.5新增API。其中LoadAdEveryLayerListener是需要实现广告事件回调的接口类。单个源维度是指TP端的一个广告位下配置多个广告源缓存，每个源的回调。
setDownloadListener(DownloadListener downloadListener)设置下载监听回调(可选 )。 快手、穿山甲等国内源支持。
V8.1.0.1新增API。
  • 参数说明
参数说明
TPAdInfo广告位ID、三方广告平台、ecpm等信息，具体请参考回调信息说明。
TPAdError广告请求失败、广告展示失败的错误码、错误信息，具体请参考错误码、错误信息说明。
  • BannerAdListener（广告位维度）
方法说明
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)广告展示失败。
V7.3.0新增回调参数TPAdError。
  • LoadAdEveryLayerListener（可选）（单个源维度）V6.4.5新增API
方法说明
onAdAllLoaded(boolean isSuccess)广告位的状态。loadAd()完毕后用于判断是否有可用广告，true表明有可用广告，false表明没有可用广告。
oneLayerLoadFailed(TPAdError adError, TPAdInfo adInfo)配置多个广告源，每个广告源加载失败后都会回调一次。
oneLayerLoaded(TPAdInfo adInfo)配置多个广告源，每个广告源加载成功后都会回调一次。
onLoadAdStart(TPAdInfo tpAdInfo)请求广告后，广告开始加载。
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新增
方法参数说明
onDownloadStartTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName开始下载回调。
TPAdInfo：广告的信息对象，具体请参考上文回调信息说明
totalBytes：文件总大小（单位：字节）
currBytes：当前已下载的大小（单位：字节）
fileName：文件名称
appName：文件对应的应用名称
onDownloadUpdateTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName,int progress下载进度更新回调。
参数意义同上。
onDownloadPauseTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName暂停下载回调。
参数意义同上。
onDownloadFinishTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName下载完成回调。
参数意义同上。
onDownloadFailTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appName下载失败回调。
参数意义同上。
onInstalledTPAdInfo tpAdInfo, long totalBytes, long currBytes, String fileName, String appNameApk安装完成回调。
参数意义同上。

三、Banner尺寸问题​

  • (1)Banner类型默认下发320 * 50 大小，部分广告源开发者可以在后台添加广告源时选择下发的尺寸。例如：Meta支持 320 * 50、320 * 90 等的尺寸下发。

  • (2)TP后台选择的尺寸需要和在三方后台申请的比例一致，选择的尺寸不一致时，展示效果不符合预期或者加载失败。
  • (3)部分广告源TP支持设置宽高，代码上设置的宽高需和后台所选尺寸保持一致。
  • (4)当代码和后台尺寸同时配置时，优先以代码设置尺寸为准。
  • (5)关于Banner的居中显示
    • 代码设置成期望的尺寸
    • 对于可以设置宽高的源，开发者将广告容器设置成期望尺寸，把TPBanner放置在容器的中间即可。
TPBanner tpBanner = new TPBanner(activity);
Map<String, Object> mLocalExtras = new HashMap<>();
mLocalExtras.put("width", 500); // 单位：dp
mLocalExtras.put("height", 250);
tpBanner.setCustomParams(mLocalExtras);

// 请求广告前设置才会生效
tpBanner.loadAd("在TP平台创建的广告位ID");
广告源是否支持后台配置多尺寸是否支持设置宽高
MetaYesNo
AdmobYesNo
MopubYesNo
AdColonyYesNo
UnityAdsYesNo
VungleYesNo
AppLovinYesNo
ChartBoostYesNo
腾讯优量汇NoNo
穿山甲国内YesYes
穿山甲海外YesYes
Mintegral国内YesYes
Mintegral海外YesYes
InmobiNoNo
FyberNoNo
StartAppNoNo
CriteoNoNo
MyTargetYesNo
AppNextYesNo
KidozNoNo
SmaatoYesNo
HuaweiYesNo
BaiduYesNo
A4GYesNo
MimoNoNo

四、三方广告网络特殊设置​

4.1 米盟Mimo Banner 支持缩放​

  • mimo sdk V5.1.7 （TradPlus V7.7.0.1）开始支持
  • 支持等比例缩放。取值（0，1] 默认1，需要开发者在请求广告前设置
// 初始化广告位
TPBanner tpBanner = new TPBanner(activity);
HashMap<String, Object> map = new HashMap<>();
//设置等比例缩放
map.put("mimo_banner_scale", "0.5");
tpBanner.setCustomParams(map);

//请求广告
tpBanner.loadAd("在TP平台创建的广告位ID");

4.2 Google自适应广告​

  • 后台配置 广告源尺寸 选择 Adaptive Banners
  • 老版本默认以屏幕宽度自适应
  • V12.9.0.1开始支持设置宽高，以传入宽高适配
// 初始化广告位
TPBanner tpBanner = new TPBanner(activity);
HashMap<String, Object> map = new HashMap<>();
//设置等比例缩放
int width = 320;//dp
int height = 50;
map.put("width", width);
map.put("height", height);
tpBanner.setCustomParams(map);

//请求广告
tpBanner.loadAd("在TP平台创建的广告位ID");

五、如何使用横幅广告位配置原生横幅​

  • TradPlus SDK V8.7.0.1开始支持，开发者首先需要在横幅广告位下添加新的广告源，横幅类型选择 原生横幅

5.1 后台配置​

  • 第一步：后台选择TradPlus横幅广告位类型（注意：选错广告位类型会没有横幅类型选项）
  • 第二步：点击编辑横幅类型中选择原生横幅类型
  • 第三步：配置三方广告网络Placement ID
注意：选择 原生横幅类型 ，创建的Placement ID不能填成 横幅 的Placement ID，否则百分比请求失败。

5.2 高级自定义渲染原生横幅广告​

  • 开发者不使用SDK内置的布局样式，自定义样式渲染原生横幅广告
private void requestAd() {
	TPBanner tpBanner = new TPBanner(activity);
    ViewGroup adContainer = findViewById(R.id.ad_container);
    adContainer.addView(tpBanner);
	
	// 自定义样式渲染原生横幅广告 loadAd前调用该方法
   // tpBanner.setNativeAdRender(new CustomAdRender());
   
   tpBanner.loadAd("在TP平台创建的广告位ID");
}

// R.layout.tp_native_banner_ad_unit为TP提供的nativebanner默认布局
// 开发者可以在SDK下载平台的res文件夹中获取
// 布局文件中的android:id: 资源ID不能改变，否则会导致自渲染广告的元素无法找到对应id而展示失败
private class CustomAdRender extends TPNativeAdRender {
        @Override
        public ViewGroup createAdLayoutView() {
            LayoutInflater inflater = (LayoutInflater) context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
            ViewGroup adLayout = (ViewGroup) inflater.inflate(R.layout.tp_native_banner_ad_unit, null);

            // 设置标题
            TextView nativeTitleView = adLayout.findViewById(R.id.tp_native_title);
            setTitleView(nativeTitleView, true);

            // 设置内容
            TextView nativeSubTitleView = adLayout.findViewById(R.id.tp_native_text);
            setSubTitleView(nativeSubTitleView, true);

            // 设置下载按钮
            TextView nativeCTAView = adLayout.findViewById(R.id.tp_native_cta_btn);
            setCallToActionView(nativeCTAView, true);

            // 设置icon
            ImageView nativeIconImageView = adLayout.findViewById(R.id.tp_native_icon_image);
            setIconView(nativeIconImageView, true);

            // 设置角标
            FrameLayout adChoiceView = adLayout.findViewById(R.id.tp_ad_choices_container);
            setAdChoicesContainer(adChoiceView, false);

            // 设置main AdChoice
            ImageView nativeAdChoice = adLayout.findViewById(R.id.tp_native_ad_choice);
            setAdChoiceView(nativeAdChoice, true);

            return adLayout;
      }
}

六、示例代码​

请参考Banner Demo

	// 1、初始化广告位。仅调用一次。
	TPBanner tpBanner = new TPBanner(activity);
    
    // 2、布局文件中添加展示广告view
	// 建议使用FrameLayout，如果使用LinearLayout，在addView的同时需要设置layoutParams
    FrameLayout adContainer = findViewById(R.id.ad_container);
    adContainer.addView(tpBanner);
        
    // 3、设置广告监听
    tpBanner.setAdListener(new BannerAdListener() {
            @Override
            public void onAdClicked(TPAdInfo tpAdInfo) {}

            @Override
            public void onAdImpression(TPAdInfo tpAdInfo) {}

            @Override
            public void onAdLoaded(TPAdInfo tpAdInfo) {}

            @Override
            public void onAdLoadFailed(TPAdError error) {
                Log.i(TAG, "onAdLoadFailed: 加载失败，code :" + error.getErrorCode() + ", msg : " + error.getErrorMsg());
            }

            @Override
            public void onAdClosed(TPAdInfo tpAdInfo) {}
        });

    // 4、设置每层广告源回调监听 （可选）
    tpBanner.setAllAdLoadListener(new LoadAdEveryLayerListener() {...});

    // 5、请求广告。广告位ID在TradPlus后台创建。广告加载成功会自动展示在你所添加的布局中。
    tpBanner.loadAd("在TP平台创建的广告位ID");