# PI ads SDK集成文档_Android(v5.0.0)
# 1. 集成准备
# 1.1 接入前准备
接入pi_ads_xxx SDK前必须先接入基础的pi_base_xxx SDK，基础SDK必须接入才能使用广告SDK！！！
# 1.2 获取SDK
# 1.3 Android Studio集成(集成方式一）
# 1.3.1 添加SDK
a. 将aar文件拷贝到应用级app下的libs文件夹中
b. 打开应用级app下的build.gradle文件添加以下代码
//依赖aar需要添加下面代码
repositories {
flatDir {
dirs 'libs'
}
}
c. 在“dependencies”中添加如下编译依赖
//添加云步ads sdk
implementation(name: 'pi_base_v5.0.0', ext: 'aar')
//添加其他依赖库
implementation 'com.android.support:appcompat-v7:27.1.1'
implementation 'com.android.support:recyclerview-v7:27.1.1'
# 1.4 Eclipse集成(集成方式二）
# 1.4.1 添加SDK
a. 将"Eclipse/libs"文件夹下所有文件复制到工程的libs文件夹下；
b. 将"Eclipse/res"文件夹下所有文件复制到工程的res文件夹下；
c. 将"Eclipse/AndroidManifest.xml"文件里的内容复制到工程的AndroidManifest.xml文件。
# 2. 接口调用
# 2.1 广告SDK初始化
初始化接口必须调用，否则SDK无法正常工作！！！
在Activity的onCreate()方法中调用初始化。
ZeusAds.getInstance().init(Activity activity);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 游戏的Activity |
# 2.2 开屏广告
开屏广告无需游戏接入接口，通过打包工具二次打包时添加。
只需执行以下4个步骤即可：
a. 在云步管理后台，广告管理-->广告位中，添加一个广告位ID为"splash_ad"，广告类型为"开屏"的广告位，配置其他值无效。
b. 在云步管理后台，广告管理-->广告单元中，添加对应渠道的开屏广告源ID，开屏标题和开屏描述，是在开屏广告请求时，默认展示的文案，必须要填写！！！
c. 在云步管理后台，广告管理-->广告位配置中，为广告位ID"splash_ad"绑定添加的广告源即可完成开屏的参数配置。
d. 使用打包工具打广告包时请勾选开屏方向，横屏或者竖屏。横屏、竖屏根据广告平台的广告源ID决定，广告平台未说明区分横竖屏开屏广告的渠道，则默认只支持竖屏开屏广告！！！广告源配置tips：在广告单元中，添加对应渠道的广告源ID时，命名建议分渠道分广告类型命名，如：华为-开屏、华为-激励视频。
广告场景tips：在展示广告时，可以传入广告场景，具体场景值自行定义，如：level_win，此参数仅做统计使用。
# 2.3 banner广告
- banner广告是横幅广告，一般是游戏在顶部或者底部，预留位置用来展示横幅广告；
# 2.3.1 创建banner广告对象
- 创建banner广告，根据云步后台创建的广告位ID新建banner广告对象。
ZeusBannerAd bannerAd = new ZeusBannerAd(Activity activity, String zeusPosId, BannerGravity gravity);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 展示广告的Activity |
| zeusPosId | String | 必须 | 云步后台创建的广告位ID |
| gravity | enum | 必须 | 展示位置，目前只支持传顶部和底部 BannerGravity.BOTTOM:底部 BannerGravity.TOP:顶部 |
# 2.3.2 设置banner广告监听器
- 在调用Banner广告的其他接口前，需设置广告事件回调的监听器，用来获取广告的事件回调，如不需要知道广告事件回调，则可以不设置监听。
bannerAd.setAdListener(IZeusBannerAdListener listener);
监听器说明:
| 回调方法 | 说明 |
|---|---|
| onAdLoaded() | 广告加载成功 |
| onAdShow(AdsInfo info) | 广告展示成功 |
| onAdClick(AdsInfo info) | 广告被点击 |
| onAdError(int code, String msg) | 广告加载失败，返回错误码和错误信息 |
| onAdClose(AdsInfo info) | 广告被关闭 |
AdsInfo说明:
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| adPlatform | AdPlatform | 广告平台，即具体的广告平台 |
| zeusPosId | String | 广告位ID，云步后台建的广告位ID，创建对象时传入 |
| sourcePosId | String | 广告源ID，即渠道的广告位ID |
| scene | String | 广告场景，调用展示接口时传入的广告场景 |
# 2.3.3 请求展示banner广告
- 调用banner的show接口后，如果广告加载成功，SDK内部会渲染广告，开发者无需关心渲染部分。
bannerAd.show();
带广告场景的接口:
bannerAd.show(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.3.4 隐藏banner广告
如果需要主动隐藏banner广告，可以调用hide接口。
如果需要再次展示广告，重新调用show方法即可。
bannerAd.hide();
# 2.3.5 销毁banenr广告对象
- 在Activity的onDestroy()函数调用此方法。
@Override
protected void onDestroy() {
super.onDestroy();
if(bannerAd != null){
bannerAd.destroy();
}
}
# 2.4 插屏广告
- 插屏是插页图片广告；
# 2.4.1 创建插屏广告对象
- 创建插屏广告，根据云步后台创建的广告位ID新建插屏广告对象。
ZeusInterstitialAd interstitialAd = new ZeusInterstitialAd(Activity activity, String zeusPosId);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 展示广告的Activity |
| zeusPosId | String | 必须 | 后台创建的广告位ID |
# 2.4.2 设置插屏广告监听器
- 在调用插屏广告的其他接口前，需设置广告事件回调的监听器，用来获取广告的事件回调，如不需要知道广告事件回调，则可以不设置监听。
interstitialAd.setAdListener(IZeusInterstitialAdListener listener);
监听器说明:
| 回调方法 | 说明 |
|---|---|
| onAdLoaded() | 广告加载成功 |
| onAdShow(AdsInfo info) | 广告展示成功 |
| onAdClick(AdsInfo info) | 广告被点击 |
| onAdError(int code, String msg) | 广告加载失败，返回错误码和错误信息 |
| onAdClose(AdsInfo info) | 广告被关闭 |
AdsInfo说明:
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| adPlatform | AdPlatform | 广告平台，即具体的广告平台 |
| zeusPosId | String | 广告位ID，云步后台建的广告位ID，创建对象时传入 |
| sourcePosId | String | 广告源ID，即渠道的广告位ID |
| scene | String | 广告场景，调用展示接口时传入的广告场景 |
# 2.4.3 加载并展示插屏广告
加载并展示插屏广告，此接口SDK内部会请求插屏广告并展示；
无论插屏是否已填充，都可以直接调用此接口去展示插屏广告；SDK内部会判断，已填充则直接展示，没填充则会主动去加载插屏广告，如果加载成功，则也会展示插屏广告；
一般情况，插屏广告没有特殊逻辑判断的话，无须调用load和show接口，直接调用此接口展示插屏广告即可。
interstitialAd.loadAndShow();
带广告场景的接口:
interstitialAd.loadAndShow(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.4.4 销毁插屏广告对象
- 在Activity的onDestroy()函数调用此方法。
@Override
protected void onDestroy() {
super.onDestroy();
if(interstitialAd != null){
interstitialAd.destroy();
}
}
# 2.5 全屏视频广告
全屏视频是插页视频广告，和激励视频广告的区别是，可以在播放过程中途选择跳过；
目前只有部分广告平台支持，oppo、vivo、广点通、穿山甲、topon、4399支持；
# 2.5.1 创建全屏视频广告对象
- 创建全屏视频广告，根据云步后台创建的广告位ID新建全屏视频广告对象。
ZeusFullScreenVideoAd fullScreenVideoAd = new ZeusFullScreenVideoAd(Activity activity, String zeusPosId);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 展示广告的Activity |
| zeusPosId | String | 必须 | 云步后台创建的广告位ID |
# 2.5.2 设置全屏视频广告事件回调监听器
- 在调用全屏视频广告的其他接口前，需设置广告事件回调的监听器，用来获取广告的事件回调，如不需要知道广告事件回调，则可以不设置监听。
fullScreenVideoAd.setAdListener(IZeusFullScreenVideoAdListener listener);
监听器说明:
| 回调方法 | 说明 |
|---|---|
| onAdLoaded() | 广告加载成功 |
| onAdShow(AdsInfo info) | 广告展示成功 |
| onAdClick(AdsInfo info) | 广告被点击 |
| onAdError(int code, String msg) | 广告加载失败，返回错误码和错误信息 |
| onAdClose(AdsInfo info) | 广告被关闭 |
| onVideoPlayStart(AdsInfo info) | 表示视频开始播放 |
| onVideoPlayFinish(AdsInfo info) | 表示视频播放完成 |
AdsInfo说明:
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| adPlatform | AdPlatform | 广告平台，即具体的广告平台 |
| zeusPosId | String | 广告位ID，云步后台建的广告位ID，创建对象时传入 |
| sourcePosId | String | 广告源ID，即渠道的广告位ID |
| scene | String | 广告场景，调用展示接口时传入的广告场景 |
# 2.5.3 加载并展示全屏视频广告
加载并展示全屏视频广告，此接口SDK内部会请求全屏视频广告并展示；
无论全屏视频是否已填充，都可以直接调用此接口去展示全屏视频广告；SDK内部会判断，已填充则直接展示，没填充则会主动去加载全屏视频广告，如果加载成功，则也会展示全屏视频广告；
一般情况，全屏视频广告没有特殊逻辑判断的话，无须调用load和show接口，直接调用此接口展示全屏视频广告即可。
fullScreenVideoAd.loadAndShow();
带广告场景的接口:
fullScreenVideoAd.loadAndShow(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.5.4 销毁全屏视频广告对象
- 在Activity的onDestroy()函数调用此方法。
@Override
protected void onDestroy() {
super.onDestroy();
if(fullScreenVideoAd != null){
fullScreenVideoAd.destroy();
}
}
# 2.6 激励视频广告
# 2.6.1 创建激励视频广告对象
- 创建激励视频广告，根据云步后台创建的广告位ID新建激励视频广告对象。
ZeusRewardVideoAd rewardVideoAd = new ZeusRewardVideoAd(Activity activity, String zeusPosId);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 展示广告的Activity |
| zeusPosId | String | 必须 | 云步后台创建的广告位ID |
# 2.6.2 设置激励视频广告事件回调监听器
- 在调用激励视频广告的其他接口前，需设置广告事件回调的监听器，用来获取广告的事件回调，如不需要知道广告事件回调，则可以不设置监听。
rewardVideoAd.setAdListener(IZeusRewardVideoAdListener listener);
监听器说明:
| 回调方法 | 说明 |
|---|---|
| onAdLoaded() | 广告加载成功 |
| onAdShow(AdsInfo info) | 广告展示成功 |
| onAdClick(AdsInfo info) | 广告被点击 |
| onAdError(int code, String msg) | 广告加载失败，返回错误码和错误信息 |
| onAdClose(AdsInfo info) | 广告被关闭 |
| onVideoPlayStart(AdsInfo info) | 表示视频开始播放 |
| onVideoPlayFinish(AdsInfo info) | 表示视频播放完成 |
| onAdReward(AdsInfo info) | 广告奖励回调，在这里可以向玩家发放奖励 |
| onAdRewardFailed(AdsInfo info) | 广告奖励失败，玩家中途关闭广告会回调此方法 |
AdsInfo说明:
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| adPlatform | AdPlatform | 广告平台，即具体的广告平台 |
| zeusPosId | String | 广告位ID，云步后台建的广告位ID，创建对象时传入 |
| sourcePosId | String | 广告源ID，即渠道的广告位ID |
| scene | String | 广告场景，调用展示接口时传入的广告场景 |
# 2.6.3 判断是否缓存有激励视频广告
判断是否有缓存的激励视频广告，返回true，表示激励视频广告已填充，可以直接调用show接口展示广告；返回false，则表示没有填充，需调用load接口去主动加载广告，加载结果可通过上述广告事件回调知道。
此接口只是判断是否有广告填充，内部不会主动加载广告，悉知！！！
boolean ready = rewardVideoAd.isReady();
# 2.6.4 请求激励视频广告
主动加载激励视频广告，当需要提前缓存激励视频广告，或者没有广告缓存时，调用加载接口去请求广告，当回调填充后（onAdLoaded），可根据需要再调用show去展示广告。
加载广告时，会回调onAdLoaded或者onAdError接口，回调onAdLoaded表示广告加载成功，回调onAdError表示广告加载失败。
激励视频广告，每次要展示广告时，判断没有缓存再去调用load加载广告即可，切勿循环判断调用！！！
加载广告接口为异步，并不是调用后立即填充，需要根据回调判断是否填充！！！
rewardVideoAd.load();
# 2.6.4 展示激励视频广告
- 当广告已填充时，调用show接口，可以展示激励视频广告；如果没填充，调用此接口无法展示广告！！！
rewardVideoAd.show();
带广告场景的接口:
rewardVideoAd.show(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.6.5 加载并展示激励视频广告
加载并展示激励视频广告，此接口SDK内部会请求激励视频广告并展示；
无论激励视频是否已填充，都可以直接调用此接口去展示激励视频广告；SDK内部会判断，已填充则直接展示，没填充则会主动去加载激励视频广告，如果加载成功，则也会展示激励视频广告；
rewardVideoAd.loadAndShow();
带广告场景的接口:
rewardVideoAd.loadAndShow(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.6.6 销毁激励视频广告
- 在Activity的onDestroy()函数调用此方法。
@Override
protected void onDestroy() {
super.onDestroy();
if(rewardVideoAd != null){
rewardVideoAd.destroy();
}
}
# 2.7 原生广告
原生广告说明：
- 目前原生广告只支持模板渲染，SDK内部会渲染素材，开发者无需关心；
- 开发者需要根据自己的游戏UI调整原生广告的坐标和宽高，自行处理屏幕适配。
# 2.7.1 创建原生广告对象
- 创建原生广告，根据云步后台创建的广告位ID新建原生广告对象。
ZeusNativeAd nativeAd = new ZeusNativeAd(Activity activity, String zeusPosId, int x, int y, int width, int height);
参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| activity | Activity | 必须 | 展示广告的Activity |
| zeusPosId | String | 必须 | 云步后台创建的广告位ID |
| x | int | 必须 | 屏幕左上角为手机屏幕坐标原点(0,0)，x为横向坐标，原生广告区域左上角，距离屏幕原点的横向距离，单位：像素 |
| y | int | 必须 | 屏幕左上角为手机屏幕坐标原点(0,0)，y为纵向坐标，原生广告区域左上角，距离屏幕原点的纵向距离，单位：像素 |
| width | int | 必须 | 原生广告宽度，单位：像素 |
| height | int | 必须 | 原生广告高度，单位：像素 |
# 2.7.2 设置原生广告事件回调监听器
- 在调用原生广告的其他接口前，需设置广告事件回调的监听器，用来获取广告的事件回调，如不需要知道广告事件回调，则可以不设置监听。
nativeAd.setAdListener(IZeusNativeAdListener listener);
监听器说明:
| 回调方法 | 说明 |
|---|---|
| onAdLoaded() | 广告加载成功 |
| onAdShow(AdsInfo info) | 广告展示成功 |
| onAdClick(AdsInfo info) | 广告被点击 |
| onAdError(int code, String msg) | 广告加载失败，返回错误码和错误信息 |
| onAdClose(AdsInfo info) | 广告被关闭 |
AdsInfo说明:
| 参数名称 | 参数类型 | 参数说明 |
|---|---|---|
| adPlatform | AdPlatform | 广告平台，即具体的广告平台 |
| zeusPosId | String | 广告位ID，云步后台建的广告位ID，创建对象时传入 |
| sourcePosId | String | 广告源ID，即渠道的广告位ID |
| scene | String | 广告场景，调用展示接口时传入的广告场景 |
# 2.7.3 判断是否缓存有原生广告
判断是否有缓存的原生广告，返回true，表示原生广告已填充，可以直接调用show接口展示广告；返回false，则表示没有填充，需调用load接口去主动加载广告，加载结果可通过上述广告事件回调知道。
此接口只是判断是否有广告填充，内部不会主动加载广告，悉知！！！
boolean ready = nativeAd.isReady();
# 2.7.4 请求原生广告
主动加载原生广告，当需要提前缓存原生广告，或者没有广告缓存时，调用加载接口去请求广告，当回调填充后（onAdLoaded），可根据需要再调用show去展示广告。
加载广告时，会回调onAdLoaded或者onAdError接口，回调onAdLoaded表示广告加载成功，回调onAdError表示广告加载失败。
nativeAd.load();
# 2.7.5 展示原生广告
- 当广告已填充时，调用show接口，可以展示原生广告；如果没填充，调用此接口无法展示广告！！！
nativeAd.show();
带广告场景的接口:
nativeAd.show(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.7.6 加载并展示原生广告
加载并展示原生广告，此接口SDK内部会请求原生广告并展示；
无论原生广告是否已填充，都可以直接调用此接口去展示原生广告；SDK内部会判断，已填充则直接展示，没填充则会主动去加载原生广告，如果加载成功，则也会展示原生广告；
一般情况，原生广告没有特殊逻辑判断的话，无须调用load和show接口，直接调用此接口展示原生广告即可。
nativeAd.loadAndShow();
带广告场景的接口:
nativeAd.loadAndShow(String scene);
广告场景参数说明:
| 参数名称 | 参数类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| scene | String | 可选 | 广告场景，自行定义即可，支持英文字母大小写和下划线 |
# 2.7.7 隐藏原生广告
- 在需要关闭原生广告时，调用hide()方法。
nativeAd.hide();
# 2.7.8 销毁原生广告
- 在Activity的onDestroy()函数调用此方法。
@Override
protected void onDestroy() {
super.onDestroy();
if(nativeAd != null){
nativeAd.destroy();
}
}
# 3. 测试
# 3.1 测试限制
- 目前SDK可以拉到测试广告，如果需要测试对应渠道的广告，需要使用打包工具打渠道包后方可测试。
# 3.2 手机限制
oppo渠道广告必须使用oppo手机测试
vivo渠道广告必须使用vivo手机测试
小米渠道广告必须使用小米手机测试
华为渠道广告必须使用华为手机测试
其他渠道广告没有限制