# 7. 广告
# 7.1 功能介绍
广告系统提供了广告聚合能力以实现与各大广告平台的一键式对接，提供了游戏间互相导流推广的能力，节省游戏接入成本。
提供了丰富的广告源和广告类型，提高媒体变现填充率和收益；
提供了高效便捷的精细化运营管理功能，动态调整广告请求排序；
借助算法让每一个广告曝光都得到最具价值的填充，从而提升广告变现收益。
# 7.2 版本变更及下载
联运广告SDK 下载
(v1.4.3.218)下载 (opens new window)
(v1.4.3.218)-Android X版本下载 (opens new window)
| 联运版本 | 更新说明 |
|---|---|
| v1.4.3.218 | 1.广告检测优化 |
| v1.4.3.204 | 1.增加广告报错埋点，方便快速定位问题 |
| v1.4.2.183 | 1.UI相关优化 |
| v1.4.2.174 | 1.优化广告展示 2.修复UI问题 |
| v1.4.1.154 | 1.优化广告配置 2.后台接口优化 |
# 7.3 接入指南
# 向运营申请接入参数
快手方运营在快手游戏发布管理后台申请创建游戏(应用)，并获取形如ksxxxxxxxx的AppId，并用于SDK的初始化。
向运营确认需要接入的广告类型 （激励视频、全屏视频、banner横幅广告等），申请对应的融合广告位id，用于后续的广告展示。
然后在快手游戏广告管理后台创建保底广告配置，将其保存为ad_config_android.ini或者ad_config_android.properties，最后将其导入到Android项目的assets目录下面。
你也可以手写配置文件！
# 广告类型:banner, video, reward, interact, splash, feed, draw
# 海外支持类型:banner, reward, interact
# 广告渠道:bytedance, gdt, kwai, admob, mint, kwaigame
# 海外支持渠道:admob
# ******************* bytedance ************************
# 请替换成您在bytedance后台申请的appId
bytedance_app_id=*********
# 请替换成您在bytedance后台申请的bannerId
bytedance_banner=*********
# 请替换成您在bytedance后台申请的videoId
bytedance_video=*********
# 请替换成您在bytedance后台申请的rewardId
bytedance_reward=*********
# 请替换成您在bytedance后台申请的interactId
bytedance_interact=*********
# 请替换成您在bytedance后台申请的splashId
bytedance_splash=*********
# 请替换成您在bytedance后台申请的feedId
bytedance_feed=*********
# 请替换成您在bytedance后台申请的drawId
bytedance_draw=*********
# 在你的工程中添加SDK
- 环境要求 Android SDK版本 >= 19
- 将广告aar导入到项目中
- adBase-release-x.x.x-x.aar (广告基础库 使用广告功能必接)
- adGuaranteed-release-x.x.x-x.aar (保底广告库 无特殊要求必接)
- adPangolin-release-x.x.x-x.aar (穿山甲广告 推荐接入 没有对应广告位配置可不接)
- adGdt-release-x.x.x-x.aar (腾讯优量汇 推荐接入 没有对应广告位配置可不接)
- adKwai-release-x.x.x-x.aar (快手广告 推荐接入 没有对应广告位配置可不接)
dependencies {
//...
implementation(name: 'adBase-release-x.x.x-x', ext: 'aar')//基础，必加
implementation(name: 'adGuaranteed-release-x.x.x-x', ext: 'aar')//保底，必加
implementation(name: 'adPangolin-release-x.x.x-x', ext: 'aar')//穿山甲，按需
implementation(name: 'adGdt-release-x.x.x-x', ext: 'aar')//广点通（优量汇），按需
implementation(name: 'adKwai-release-x.x.x-x', ext: 'aar')//快手，按需
}
# 广告使用
注意 广告功能在隐私同意之后才会初始化，同意隐私之前调用无效
| 广告类型 | 广告说明 |
|---|---|
| ADConstant.AD_TYPE_BANNER | 横幅 |
| ADConstant.AD_TYPE_INTERACTION | 插屏 |
| ADConstant.AD_TYPE_VIDEO | 全屏视频 |
| ADConstant.AD_TYPE_REWARD_VIDEO | 激励视频 |
| ADConstant.AD_TYPE_SPLASH | 闪屏 |
| ADConstant.AD_TYPE_FEED | 信息流 |
| ADConstant.AD_TYPE_DRAW | Draw |
# 1. 注册广告：
展示之前需要先注册（App启动后 同一个广告位只需要调用一次）
/**
* @param position 融合广告位名称（运营提供）
* @param adType 广告类型
*/
KwaiSdk.registerPosition(String position, int adType);
// 代码示例 注册融合广告位
KwaiSdk.registerPosition("激励视频1", ADConstant.AD_TYPE_REWARD_VIDEO);
# 2. 展示广告
/**
* @param activity 当前activity
* @param position 融合广告位名称（运营提供）
* @param scene 游戏场景（游戏研发自定义）
* @param listener 广告回调
*/
KwaiSdk.showAD(Activity activity, String position, String scene, OnADListener listener);
# 3. 回调方法
OnADListener
/**
* 资源成功加载的回调
* @param channel 广告渠道
* @param slotId 广告位
* @param code 错误码 成功0;
* @param msg 错误信息
*/
public void onAdLoad(String channel, String slotId, int code, String msg);
/**
* 广告展示回调
* @param channel 广告渠道
* @param slotId 广告位
*/
public void onAdShow(String channel, String slotId);
/**
* 广告被点击 (包含点击跳转、点击下载，不做细分)
* @param channel 广告渠道
* @param slotId 广告位
*/
public void onAdClick(String channel, String slotId);
/**
* 广告被关闭
* @param channel 广告渠道
* @param slotId 广告位
*/
public void onAdClose(String channel, String slotId);
/**
* 广告展示完成，包含非正常结束。视频跳过，播放错误等。
* @param channel 广告渠道
* @param code 错误码 {@link ADCode}是否完成激励要求 0 成功
* @param msg 错误信息
*/
public void onAdCompletion(String channel, int code, String msg);
/**
*激励视频有效性回调
* @param channel 广告渠道
* @param slotId 广告位 id
* @param code 错误码 {@link ADCode}是否完成激励要求 0 成功
* @param msg 错误信息
**/
public void onAdReward(String channel, String slotId, int code, String msg);
# 4. 激励视频
由于当前发奖接口兼容了各个不同的广告渠道平台，为了统一不同渠道处理发奖，需要研发按照以下方式做兼容处理：
a. 在onadshow回调中记录一个广告播放的标记A
b. 在onadreward回调中记录一个广告发奖的标记B
c. 在onadComplete回调中记录一个广告播放完成的标记C，广告播放完成的code为0
d. 在onadClose回调中处理发奖逻辑，条件为：
onadshow广告播放条件必须达成
onadreward和onadComplete两个条件达成一个
e. 由于不同游戏对发奖逻辑有不同的理解和设计，此处可以根据实际需求进行设置。
f. 优量汇的广告必须完整的观看完成并返回到下载落地页后，才会给到onreward回调。（目前已知）
//激励视频展示代码示例
KwaiSdk.showAD(activity, "运营提供的融合广告位名称-激励视频", "scene-reward-1", rewardlistener);
# 5. banner广告
//banner展示代码示例
KwaiSdk.showAD(activity, "运营提供的融合广告位名称-banner", "填写展示场景名称", bannerlistener);
//隐藏Banner
KwaiSdk.hideAD(ADConstant.AD_TYPE_BANNER);
/**
* 位置类型
* AD_BANNER_LOCATION_TOP = Gravity.TOP | Gravity.CENTER_HORIZONTAL;
* AD_BANNER_LOCATION_MIDDLE = Gravity.CENTER;
* AD_BANNER_LOCATION_BOTTOM = Gravity.BOTTOM | Gravity.CENTER_HORIZONTAL;
*/
Position position = new Position();
//设置坐标
position.setGravity(ADConstant.AD_BANNER_LOCATION_BOTTOM);
//设置宽高
position.setExpertWidth(width); //仅支持bytedance
position.setExpertHeight(height);//仅支持bytedance
//设置广告顶部
KwaiSdk.setADPosition(ADConstant.AD_TYPE_BANNER, Position position);
# 6. feed广告
//代码示例
KwaiSdk.showAD(activity, "运营提供的融合广告位名称-feed", "填写展示场景名称", feedlistener);
//设置大小和宽高
Position position = new Position();
position.setGravity(ADConstant.AD_BANNER_LOCATION_BOTTOM);
position.setExpertWidth(width); //仅支持穿山甲、优量汇、快手
position.setExpertHeight(height);//仅支持穿山甲、优量汇、快手
//设置广告坐标宽高
KwaiSdk.setADPosition(ADConstant.AD_TYPE_FEED, Position position);
# 7. 闪屏广告
前提：由于开屏广告第一次展示广告前需要缓存广告到本地，广告加载需要占用设备一定的带宽及下载时间，建议游戏在广告注册的代码处添加loading页，为广告缓存提供一个下载环境。
- 冷启动：游戏loading页调用判断当前广告是否缓存广告完成，如果完成则调用showad展示闪屏广告，如果广告在游戏设置loading结束时仍未缓存成功，则跳过此次开屏播放，建议缓存时间5s左右。建议本地缓存判断方法每秒执行一次，5次后放弃。并将开屏广告的注册提升到所有广告注册之前。
- 热启动：配置开启热启动
//判断当前缓存广告数量
int adsize = KwaiSdk.getCacheSuccessVideoSize(ADConstant.AD_TYPE_SPLASH)；
//当缓存的广告>0时，展示闪屏广告
if (adsize > 0){
KwaiSdk.showAD(activity, "运营提供的融合广告位名称", "0", listener);
}
//开启冷启动自动展示闪屏
KwaiSdk.setSplashAutoShow(true);
//SDK已实现热启动逻辑，需要在代码中开启热启动功能
KwaiSdk.enableHotStartSplash("运营提供的融合广告位名称 - 闪屏");
# 8. 广告埋点
基础埋点SDK已经完成预置，只需要传入对应场景参数即可
/**
* @param adType 广告类型
* @param scene 运营提供的广告播放场景标识，此参数作为打点数据 上报
* @param position 运营在快手游戏发布后台配置的融合广告位名称
**/
KwaiSdk.reportADButtonShow(int adType, String scene, String position);
// 通知SDK发送广告奖励完毕 在游戏给用户发放激励奖励完成后调用。
KwaiSdk.reportAdRewardComplete();
# 9. 错误码
| 错误码 | 描述 |
|---|---|
| 0 | 成功 |
| 101 | 失败 |
| 102 | params INVALID |
| 103 | method unsupport |
| 104 | video skip |
| 105 | video play invalid |
| 106 | repeat load , so cancel |
| 107 | network unusable |
| 108 | 广告曝光回调失败，但是close成功回调 |
| 109 | 广告加载超时 |
| 110 | 广告SDK内部异常 |
| -200003 | 未配置广告位信息 |
| -200004 | 没有可以展示的广告 |
| -200005 | 获取广告appid失败 |
| -200006 | 未配置广告位 |
| -200007 | 本地视频播放次数超过限制 |
| -200008 | 广告播放多次出现异常，请更换良好的网络 |
| -200009 | 广告曝光达到上限 |
| -200010 | 广告请求频繁，请稍后再试 |
| -10014 | 广告已过期 |
← 6. 支付 8. Schema 功能 →