开屏广告

一、集成建议

主要介绍在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)【V9.9.0.1以下版本】 不建议在onAdLoaded回调中直接执行广告展示的方法：
  • SDK有广告过期自动补充功能，加载成功后会回调onAdLoaded
  • onAdLoaded回调中直接showAd()，会导致过期补充或自动加载成功后弹出广告影响用户体验
  • 建议：开发者记录onAdLoaded状态，在需要展示广告的地方，先判断isReady()返回true，再展示广告
• (3)【V9.9.0.1 + 】优化回调机制，调用一次loadAd()才会收到一次loaded回调。
  • 开发者可以直接在onAdLoaded回调中执行广告展示
• (4)广告关闭后，开发者需要在onAdClosed回调中remove传入容器。
• (5)开发者需注意如果已经进入app内部，而加载时间过长，这次load结果就不应该展示了。

广告平台注意事项

广告平台	说明
米盟	V7.2.0.1支持开屏。loaded成功后会自动展示，不支持预加载。
Huaiwei	V8.4.0.1支持开屏。需要使用loadAd(ViewGroup adContainer)方法。loaded成功后会自动展示，不支持预加载。 V12.9.0.1支持预加载，可以先加载后展示（后台配置的时，需要选择先缓存后展示）

二、API说明

1、TPSplash API

• 创建广告位对象

方法	说明
TPSplash(Activity activity, String adUnitId)	仅初始化时调用一次。 以下广告平台时必须传入Activity: TapTap 、BeiZi 、Mintegral-CN、Vivo，如果不传会导致广告加载失败； Admob相关 、Pangle、Yandex ，如果不传会导致广告展示失败。 adUnitId是在TP平台创建的广告位ID。

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

方法	说明
loadAd(null)	请求广告。可以使用预加载功能(配置缓存个数)。 和showAd(adContainer)配套使用。
showAd(ViewGroup adContainer)	展示广告并传入容器。 容器推荐使用FrameLayout。

• 加载、展示广告 （方法二）（米盟，华为使用）

方法	说明
loadAd(ViewGroup adContainer)	请求广告。 容器推荐使用FrameLayout。 注意使用该方法请求，不支持预加载(不能配置缓存个数)
showAd(null)	展示广告。和loadAd(adContainer)配套使用。米盟、华为开屏不支持预加载，loaded成功后会自动展示，不需要调show。

• 进入广告场景

方法	说明
entryAdScenario(String sceneId)	进入广告场景,sceneId 广告场景ID。 V10.0.1.0开始支持。 开发者需合showAd(adContainer,sceneId)配套使用。

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

方法	说明
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)	广告加载成功。 V9.9.0.1优化回调机制，开发者主动调用一次load才会对应回调一次loaded,不调用不回调。
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

注意1：选择原生开屏类型，创建的Placement ID不能填成开屏的Placement ID，否则百分比请求失败。 注意2：因华为广告平台大部分广告没有icon等重要的广告元素，如果使用自渲染方式，需要您针对华为广告源单独处理，否则广告icon元素位置会显示空白。

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

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

private void requestAd() {
	TPSplash tpSplash = new TPSplash(activity,"在TP平台创建的广告位ID");
	
	// 自定义样式渲染原生开屏广告 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,"在TP平台创建的广告位ID");
//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(null);
......
	// 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、Bigo设置Icon

• 在loadAd前调用
• 在Bigo后台创建广告位时需要选择半屏样式，TradPlus后台也是
• Bigo设置底部icon，样式无法自定义，属于Bigo设置好的样式，不支持自定义

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

5、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);

6、Google 设置横屏

• 在loadAd前调用
• V13.6.0.1 适配 Google V24.0.0该版本起设置不会生效
• Google 在V24.0.0版本移除横竖屏API

private int mOrientation = 2;//2横屏，默认竖屏

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