开屏广告

一、集成建议

主要介绍在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和onAdLoadFailed回调中执行广告加载的方法。对广告平台方来说，短时间内多次请求，不容易得到填充，同时会造成多次无效请求，也可能会导致应用卡顿；如果产品逻辑要在这里发起请求，开发者需要控制时间间隔和次数，比如分别在10S、30S、60S后发起请求。
• (2)不建议在onAdLoaded回调中直接执行广告展示的方法，这可能导致用户体验不佳，SDK有广告会过期自动补充功能，加载成功后会回调onAdLoaded。开发者无法精准控制广告展示的时机。可配合产品逻辑在收到onAdLoaded回调后，判断isReady()是否有可用广告，再展示广告。
• (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。
Huaiwei	V8.4.0.1支持开屏。需要使用loadAd(ViewGroup adContainer)方法。loaded成功后就需要展示，不支持预加载。
TapTap	V9.7.10.1支持开屏。没有提供点击回调和展示回调，TP在关闭广告时回调了展示，补充埋点。

二、API说明

1、TPSplash API

• 创建广告位对象

方法	说明
TPSplash(Activity activity, String adUnitId)	仅初始化时调用一次。 以下广告平台时必须传入Activity: Admob 、Pangle、TapTap,否则会导致广告无法加载成功。

• 加载、展示广告（方法一）

方法	说明
loadAd(ViewGroup adContainer)	请求广告。 容器推荐使用FrameLayout。 注意使用该方法请求，无法使用预加载(不能配置缓存个数),每次请求广告均实时发起。
showAd(null)	展示广告。和loadAd(adContainer)配套使用。米盟开屏不支持预加载，loaded成功后就需要展示。

• 加载、展示广告 （方法二）（推荐）

方法	说明
loadAd(null)	请求广告。可以使用预加载功能(配置缓存个数)。 和showAd(adContainer)配套使用。
showAd(ViewGroup adContainer)	展示广告并传入容器。 容器推荐使用FrameLayout。 米盟、华为开屏不支持预加载，loaded成功后就需要展示。

• 检测是否有可用广告（可选）

方法	说明
isReady()	V6.2.4新增API。检查是否有可用广告，true为有可用广告。

• 自定义渲染的方式设置原生拼接开屏（可选）

方法	说明
setNativeAdRender(TPNativeAdRender nativeAdRender)	自定义渲染的方式设置原生拼接开屏(可选)。V8.7.0.1新增API （1）8.7.0.1开始支持使用开屏广告位配置原生拼接开屏，SDK内置默认布局样式，如果开发者需要自己定义布局样式，就需要使用此方法渲染。 （2）详细了解，见下文《如何使用开屏广告位配置原生拼接开屏》部分介绍

• 配置三方广告源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)	广告被点击。V9.7.10.1新增的Taptap暂不支持点击回调。
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。
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安装完成回调。 参数意义同上。

三、如何使用开屏配置原生开屏

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

1、后台配置

• 第一步：后台选择TradPlus开屏广告位类型（注意：选错广告位类型会没有开屏类型选项）
• 第二步：点击编辑开屏类型中选择原生开屏类型
• 第三步：配置三方广告网络Placement ID

注意：选择　**原生开屏类型**　，创建的Placement ID不能填成　**开屏**　的Placement ID，否则百分比请求失败。

2、高级自定义渲染原生开屏广告

• 开发者不使用SDK内置的布局样式，自定义样式渲染原生开屏广告

private void requestAd() {

TPSplash tpSplash = new TPSplash(activity,"AdUnitId");

// 自定义样式渲染原生开屏广告 loadAd前调用该方法

// tpSplash.setNativeAdRender(new CustomAdRender());

tpSplash.loadAd();

}

// R.layout.tp_native_splash_ad 为开发者自己使用原生布局拼接成的开屏

// 开发者可以在SDK下载平台的res文件夹中获取tp_native_splash_ad.xml

// 布局文件中的android:id: 资源ID不能改变，否则会导致自渲染广告的元素无法找到对应id而展示失败

public class CustomAdRender extends TPNativeAdRender {

@Override

public ViewGroup createAdLayoutView() {

LayoutInflater inflater = (LayoutInflater) NativeSplashActivity.this.getSystemService(Context.LAYOUT_INFLATER_SERVICE);

ViewGroup adLayout = (ViewGroup) inflater.inflate(R.layout.tp_native_splash_ad, 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);

// 设置main image

ImageView nativeMainImageView = adLayout.findViewById(R.id.tp_mopub_native_main_image);

setImageView(nativeMainImageView, true);

// 设置角标

FrameLayout adChoiceView = adLayout.findViewById(R.id.tp_ad_choices_container);

setAdChoicesContainer(adChoiceView, false);

return adLayout;

}

}

四、示例代码

请参考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前调用这个方法
• Pangle设置底部icon，样式无法自定义，属于pangle设置好的样式，不支持自定义

Map<String, Object> mLocalExtras = new HashMap<String, Object>();

mLocalExtras.put("app_icon", R.drawable.icon);

tpSplash.setCustomParams(mLocalExtras);

4、Mintegral设置Icon

• 如果需要设置，开发者在loadAd前调用这个方法
• MTG V8801起也支持设置icon
• 宽高默认值100,100,单位：px
• icon的宽高不能超过屏幕的25%

Map<String, Object> mLocalExtras = new HashMap<String, Object>();

mLocalExtras.put("app_icon_mtg", R.drawable.icon);

mLocalExtras.put("app_icon_width", 100); // Icon 宽

mLocalExtras.put("app_icon_height", 100); // Icon 高

tpSplash.setCustomParams(mLocalExtras);