Skip to main content

开屏广告

一、集成建议#

主要介绍在Android项目中如何集成 TradPlus SDK的开屏广告:

  • 开屏广告是打开app的时候展示一个3-5s的全屏的广告。
  • 开屏广告分冷启动和热启动,冷启动时要尽可能提前开始加载广告,这样才能确保在进入app之前加载到并展示广告。
  • 热启动是app切换到后台,并没有真正的退出,这种情况下要能检测到并提前加载广告。
  • 开屏广告一般要配合app的启动页来使用,在加载的时间先给用户看启动页,等广告加载成功后展示广告,广告结束进入app内部。

1、开屏广告的推荐用法#

应用启动方式#

  • 冷启动:当启动应用时,后台没有该应用的进程,这时系统会重新创建一个新的进程分配给该应用,这种方式叫“冷启动”
  • 热启动:当启动应用时,后台已有该应用的进程,例:按home键推出再回到前台,或切换应用回到前台等,这种方式叫“热启动”

2、开屏加载策略#

(1)冷启动方式打开应用#

  • 第一时间在后台load广告,同时建议在loading页时最多停留5秒
    • 如果5秒内返回广告,直接显示。显示完后,再调用 load 方法加载一条广告,供下次热启动时使用
    • 如果5秒内未返回广告,则关闭loading页,直接进入应用主界面。如在此之后收到 loaded 回调,不要再调用show方法。本次广告不会丢弃,SDK会缓存下来备用
  • 应用冷启动时,加载广告的过程中尽量不要同时请求其他网络资源,以免影响广告加载速度

(2)热启动方式打开应用#

  • 有广告则直接显示
  • 不管有无广告展示,都需要再加载一条新的广告,作为备用
  • 如果应用能够监听到切换后台事件,可在切换后台时调用 isReady 方法判断广告是否Ready,如果没有Ready,可补充一条广告

3、开屏出现时机#

推荐示例:

在下面的推荐示例中,开屏广告在应用的加载屏幕上显示。


不推荐示例:

如果用户已经进入应用Home页,则不要展示开屏广告。否则会突然弹出,容易造成用户误点击。

4、注意事项#

  • (1)禁止在oneLayerLoadFailed 回调中执行广告加载的方法,否则会引起多个无用请求。
  • (2)广告关闭后,开发者需要在onAdClosed回调中remove传入容器。
  • (3)开发者需注意如果已经进入app内部,而加载时间过长,这次load结果就不应该展示了
支持开屏广告的广告网络#
广告网络说明
快手使用预加载(V6.4.5新功能),调用show()前需要刷新context
腾讯优量汇V6.4.4支持开屏V+。V7.0.10.0开始支持半屏展示。
穿山甲(国内)V6.4.4支持开屏点睛。
谷歌Admob(海外)AndroidX版本支持,Support版本不支持。需要在创建TPSplash传入Activity。
百度V6.6.0开始支持。
游可赢V6.9.5开始支持。
Sigmob无注意事项。
Mintegral无注意事项。
交叉推广无注意事项。
米盟V7.2.0.1支持开屏。loaded成功后就需要展示,不支持预加载。
Pangle海外V7.6.0.1支持开屏。需要在创建TPSplash传入Activity。

二、API说明#

1、TPSplash API#

  • 初始化广告位
方法说明
TPSplash(Activity activity, String adUnitId)初始化广告位。AdUnitId广告位ID在TradPlus后台创建。仅初始化时调用一次。
以下广告平台时必须传入Activity: Admob 、Pangle,否则会导致广告无法加载成功。
  • 加载、展示广告(方法一)
方法说明
loadAd(ViewGroup adContainer)请求广告。
容器推荐使用FrameLayout
注意使用该方法请求,无法使用预加载(不能配置缓存个数),每次请求广告均实时发起。
showAd(null)展示广告。和loadAd(adContainer)配套使用。米盟开屏不支持预加载,loaded成功后就需要展示。
  • 加载、展示广告 (方法二)(推荐)
方法说明
loadAd(null)请求广告。可以使用预加载功能(配置缓存个数)。showAd(adContainer)配套使用。
showAd(ViewGroup adContainer)展示广告并传入容器。
容器推荐使用FrameLayout
米盟开屏不支持预加载,loaded成功后就需要展示。
  • 检测是否有可用广告(可选)
方法说明
isReady()V6.2.4新增API。检查是否有可用广告,true为有可用广告。
  • 配置三方广告源config配置(可选)
方法说明
setDefaultConfig("config")用于提升冷启动的加载速度,可以提前内置一套默认配置,这样在首次安装并打开app后第一时间会根据这份配置请求三方广告平台。
在AndroidStudio的log中过滤“TPSplash”的TAG,把内容复制出来,调用setDefaultConfig来设置。
这个接口只会在首次安装后第一次打开app生效,后续有正式配置下载下来,就不会再使用这份配置(清除app本地缓存后也会使用这次的配置)。
  • 自定义key-value(可选)
方法说明
setCustomParams(map)需要在loadAd前调用该方法。具体使用见上文腾讯半屏展示API的注意事项

2、监听回调API#

  • 设置广告监听
方法说明
setAdListener(SplashAdListener listener)设置广告监听回调,其中SplashAdListener是需要实现广告事件回调的接口类。
setAllAdLoadListener(LoadAdEveryLayerListener everyLayerListener)(可选)V6.4.5新增API。设置单个源维度的监听回调。其中LoadAdEveryLayerListener是需要实现广告事件回调的接口类。
单个源维度是指TP端的一个广告位下配置多个广告源缓存,每个源的回调。
setDownloadListener(DownloadListener downloadListener)设置下载监听回调(可选 )。 快手、穿山甲等国内源支持。
V8.1.0.1新增API
  • 监听回调中的参数说明
参数说明
TPAdInfo广告位ID、三方广告平台、ecpm等信息,具体请参考回调信息说明
TPAdError广告请求失败、广告展示失败的错误码、错误信息,具体请参考错误码、错误信息说明
  • SplashAdListener说明(广告位维度)
方法说明
onAdClicked(TPAdInfo tpAdInfo)广告被点击。
onAdImpression(TPAdInfo tpAdInfo)广告被展示。
onAdClosed(TPAdInfo tpAdInfo)广告被关闭。必须在该回调中处理广告关闭逻辑,把传入容器remove。
onAdLoaded(TPAdInfo tpAdInfo, TPBaseAd tpBaseAd)广告加载成功。
onAdLoadFailed(TPAdError error)广告加载失败。
onAdShowFailed(TPAdInfo tpAdInfo,TPAdError tpAdError)广告展示失败。
V7.3.0新增回调参数TPAdError
onZoomOutStart(TPAdInfo tpAdInfo)V6.4.4新增API。开屏点睛开始。仅穿山甲(国内)和腾讯优量汇支持。
onZoomOutEnd(TPAdInfo tpAdInfo)V6.4.4新增API。开屏点睛关闭。仅穿山甲(国内)和腾讯优量汇支持。
  • LoadAdEveryLayerListener说明(可选)(单个源维度)
方法说明
onAdAllLoaded(boolean isSuccess)广告位的状态。loadAd()完毕后用于判断是否有可用广告,true表明有可用广告,false表明没有可用广告。
oneLayerLoadFailed(TPAdError adError, TPAdInfo adInfo)配置多个广告源缓存,当每个广告源加载失败后会都会回调一次。
oneLayerLoaded(TPAdInfo adInfo)V6.4.5新增API。配置多个广告源缓存,当每个广告源加载成功后会都会回调一次。
onLoadAdStart(TPAdInfo tpAdInfo)请求广告后,广告开始加载。
V7.9.0 废弃。
oneLayerLoadStart(TPAdInfo tpAdInfo)每层waterfall 向三方广告源发起请求前,触发的回调。V7.9.0 新增。
onAdStartLoad(String adUnitId)每次调用load方法时返回的回调,包含自动加载等触发时机。V7.9.0 新增。
onBiddingStart(TPAdInfo tpAdInfo)V6.4.5新增API。Bidding开始加载。
onBiddingEnd(TPAdInfo tpAdInfo,TPAdError tpAdError)V6.4.5新增API。Bidding加载完成。
V7.3.0新增回调参数TPAdError
  • 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安装完成回调。
参数意义同上。

三、示例代码#

请参考Splash Demo

//1、初始化广告位。广告位ID在TradPlus后台创建。仅调用一次。
//注意快手的sdk需要传入的activity是FragmentActivity,否则无法展示快手开屏
TPSplash tpSplash = new TPSplash(activity,"AdUnitId");
//2、设置回调监听
tpSplash.setAdListener(new SplashAdListener() {
@Override
public void onAdClicked(TPAdInfo tpAdInfo) {}
@Override
public void onAdImpression(TPAdInfo tpAdInfo) {}
@Override
public void onAdClosed(TPAdInfo tpAdInfo) {
// 广告关闭后,要把开屏页面关闭,如果是跟内容在同一个activity,这里把开屏的容器remove掉
SplashActivity.this.finish();
}
@Override
public void onAdLoaded(TPAdInfo tpAdInfo, TPBaseAd tpBaseAd) {
// 加载成功
}
});
// 3、设置每层广告源回调监听 (可选)
tpSplash.setAllAdLoadListener(new LoadAdEveryLayerListener() {...});
// 4、请求广告
tpSplash.loadAd();
......
// 5、检查是否有可用广告
//这里一定要注意,需要判断一下是否已经进入app内部,如果加载时间过长,已经进入到app内部,这次load结果就不应该展示了
if (tpSplash.isReady()) {
// 6、展示广告。 需要传入一个容器(容器一般要求全屏或者至少占屏幕75%以上)
tpSplash.showAd(adContainer);
}

四.三方广告网络特殊设置#

1.腾讯半屏展示API#

  • 开屏半屏广告的显示区域其高度要大于设备高度的75%(建议值大于80%),最小高度要大于400dp,开屏广告默认只在竖屏展示,横屏一般不满足尺寸要求。详细注意事项请看优量汇开屏广告接入注意事项
  • V7.0.10.1开始支持腾讯开屏半屏设置。默认全屏展示,当需要展示半屏广告时候,传入1。
  • 该API需要在请求广告前调用。
// 初始化广告位
TPSplash tpSplash = new TPSplash(activity,"AdUnitId");
HashMap<String, Object> map = new HashMap<>();
//设置腾讯半屏广告,竖屏展示
map.put("GDT_halfSplash", 1);
tpSplash.setCustomParams(map);
//请求广告
tpSplash.loadAd(null);

2.集成快手并使用预加载#

  • V6.4.5新增API集成快手,同时使用预加载,每次进入showAd(viewGroup)的场景时,需要刷新context,不然快手无法加载成功。
    refreshContext在showAd(viewGroup)方法前调用。
// 初始化广告位
TPSplash tpSplash = new TPSplash(activity,"AdUnitId");
//预加载使用方式 请求广告
tpSplash.loadAd(null);
....
// 刷新Context
GlobalTradPlus.getInstance().refreshContext(context);
// 展示广告
tpSplash.showAd(adContainer);

3.Pangle海外超时问题和设置Icon#

(1)第一次请求可能会超时的问题#

由于Pangle端第一次请求是没有进行预加载,延长超时时间就能解决这个问题; SDK设置的默认缓存时长是5秒。正常超时时常设置为15s有较大几率第一次就能拿到广告。如果需要设置,在loadAd前调用这个方法即可。

Map<String, Object> mLocalExtras = new HashMap<String, Object>();
mLocalExtras.put("time_out", 15000);
tpSplash.setCustomParams(mLocalExtras);

(2)Pangle支持设置底部Icon问题#

如果需要设置,开发者在loadAd前调用这个方法即可

Map<String, Object> mLocalExtras = new HashMap<String, Object>();
mLocalExtras.put("app_icon", R.drawable.icon);
tpSplash.setCustomParams(mLocalExtras);