# 广告

# 激励视频广告

# 功能介绍

接入简单，广告展示位置灵活控制
支持激励视频广告，收入回报丰厚
通过监听用户关闭广告来发放奖励

激励视频广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在上屏 Canvas 上。开发者可以调用 ks.createRewardedVideoAd 创建激励视频广告组件。该方法返回的是一个全局单例。

let video1 = ks.createRewardedVideoAd({ adUnitId: 'xxxx' })
let video2 = ks.createRewardedVideoAd({ adUnitId: 'xxxx' })
console.log(video1 === video2)
// true

激励视频广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。

let rewardedVideoAd = ks.createRewardedVideoAd({ adUnitId: 'xxxx' })

# 显示/隐藏

激励视频广告组件默认是隐藏的，需要调用 RewardedVideoAd.show() 进行显示。
只有在用户点击激励视频广告组件上的 关闭广告 按钮时，广告才会关闭。开发者不可控制激励视频广告组件的隐藏。

rewardedVideoAd.show()
.then(() => console.log('激励视频 广告显示'))

如果显示失败，通过 RewardedVideoAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。

rewardedVideoAd.onError(err => {
  console.log(err)
})

RewardedVideoAd.show() 返回的 Promise 也会是一个 rejected Promise。

rewardedVideoAd.show()
.catch(err => console.log(err))

# 监听用户关闭广告

只有在用户点击激励视频广告组件上的 关闭广告 按钮时，广告才会关闭。这个事件可以通过 RewardedVideoAd.onClose() 监听。开发者需要根据 res.isEnded 判断是否视频是否播放结束、可以向用户下发奖励。

rewardedVideoAd.onClose(res => {
    // 用户点击了【关闭广告】按钮
    if (res && res.isEnded || res === undefined) {
      // 正常播放结束，可以下发游戏奖励
    }
    else {
        // 播放中途退出，不下发游戏奖励
    }
})

# 相关API

接口	功能说明
ks.createRewardedVideoAd	获取全局激励视频广告组件
RewardedVideoAd	激励视频广告组件
RewardedVideoAd.destroy	销毁激励视频广告实例
RewardedVideoAd.offClose	取消监听激励视频广告关闭事件
RewardedVideoAd.offError	取消监听激励视频错误事件
RewardedVideoAd.onClose	监听激励视频广告关闭事件
RewardedVideoAd.onError	监听激励视频错误事件
RewardedVideoAd.show	显示激励视频广告

# 插屏广告

# 功能介绍

接入简单，广告展示位置灵活控制

插屏广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在上屏 Canvas 上。开发者可以调用 ks.createInterstitialAd 创建插屏广告组件。该方法会新创建一个插屏广告实例。

let interstitial1 = ks.createInterstitialAd({ adUnitId: 'xxxx' })
let interstitial2 = ks.createInterstitialAd({ adUnitId: 'xxxx' })
console.log(interstitial1 === interstitial2)
// false

插屏广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。

let InterstitialAd = ks.createInterstitialAd({ adUnitId: 'xxxx' })

# 显示/隐藏

插屏广告组件默认是隐藏的，需要调用 InterstitialAd.show() 进行显示。
只有在用户点击插屏广告组件上的 关闭广告 按钮时，广告才会关闭。开发者不可控制插屏广告组件的隐藏。

InterstitialAd.show()
.then(() => console.log('插屏 广告显示'))

如果显示失败，通过 InterstitialAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。

InterstitialAd.onError(err => {
  console.log(err)
})

InterstitialAd.show() 返回的 Promise 也会是一个 rejected Promise。

InterstitialAd.show()
.catch(err => console.log(err))

# 监听用户关闭广告

只有在用户点击插屏广告组件上的 关闭广告 按钮时，广告才会关闭。这个事件可以通过 InterstitialAd.onClose() 监听。

InterstitialAd.onClose(res => {
    // 用户点击了【关闭广告】按钮
})

# 相关API

接口	功能说明
ks.createInterstitialAd	获取插屏广告组件
InterstitialAd	插屏广告组件
InterstitialAd.destroy	销毁插屏广告实例
InterstitialAd.offClose	取消监听插屏广告关闭事件
InterstitialAd.offError	取消监听插屏错误事件
InterstitialAd.onClose	监听插屏广告关闭事件
InterstitialAd.onError	监听插屏错误事件
InterstitialAd.show	显示插屏广告

# 功能介绍

由客户端原生的图片、文本控件组成的原生组件，层级最高，会覆盖在上屏 Canvas 上。
本方法需在高版本App上运行，使用前请做兼容检查
开发者可以调用 ks.createBannerAd 创建 Banner 广告组件。Banner 广告组件在创建后会自动拉取广告数据并进行渲染，开发者只需要控制 Banner 广告组件的位置和显示/隐藏即可。

const { windowWidth, windowHeight } = ks.getSystemInfoSync();
const targetBannerAdWidth = 320;

// 创建一个居于屏幕底部正中的广告
let bannerAd = ks.createBannerAd({
  adUnitId: "xxxx",
  style: {
    width: targetBannerAdWidth,
    left: (windowWidth - targetBannerAdWidth) / 2,
    top: windowHeight - targetBannerAdWidth / 5, // 根据系统约定尺寸计算出广告高度
  },
});

bannerAd.show()

# 显示/隐藏

Banner 广告组件默认是隐藏的，需要调用 BannerAd.show() 进行显示。

bannerAd.show()

当切换到没有 Banner 广告组件的场景或页面时，调用 BannerAd.hide() 隐藏 Banner 广告组件。

bannerAd.hide()

# 广告拉取成功与失败

BannerAd 在创建后会拉取广告。如果拉取失败，通过 BannerAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。

bannerAd.onError(err => {
  console.log(err)
})

BannerAd.show() 返回的 Promise 也会是一个 rejected Promise。

bannerAd.show()
.catch(err => console.log(err))

如果拉取成功，bannerAd.show() 返回的 Promise 也会是一个 resolved Promise。两者的回调函数中都没有参数传递。

bannerAd.show()
.then(() => console.log('banner 广告显示'))

# onResize

开发者在创建 BannerAd 时设置宽度和位置，也可以在创建后设置。

let bannerAd = ks.createBannerAd({
  adUnitId: 'xxxx',
  style: {
    left: 10,
    top: 76,
    width: 320
  }
})

bannerAd.show()
bannerAd.style.left = 20
bannerAd.style.width = 300

Banner 广告组件的尺寸会根据开发者设置的宽度，即 style.width 进行等比缩放，缩放的范围是 300 到屏幕宽度。当 style.width 小于 300 时，会取作 300。当 style.width 大于屏幕宽度时，会取作屏幕宽度。在组件内部会以此值为基准，根据 Banner 广告的标准尺寸，进行缩放。

屏幕宽度是以逻辑像素为单位的宽度，通过 ks.getSystemInfoSync() 可以获取到。

let { screenWidth } = ks.getSystemInfoSync()

每当缩放发生且缩放后的尺寸不同时，通过 BannerAd.onResize() 注册的回调函数就会执行。回调函数的参数类型是一个object，其属性是resize后的真实宽高。

bannerAd.onResize(res => {
  console.log(res.width, res.height)
})

如果在 onResize 的回调函数中重设 width 且总是与上一次缩放后的 width 不同，那么可能会导致 onResize 的回调函数一直触发，并卡死在 onResize 的回调函数中。

bannerAd.onResize(res => {
  // 错误
  bannerAd.style.width = res.width + Math.random()*10
})

# 创建新的 BannerAd，销毁旧的 BannerAd

每个 BannerAd 实例在创建后会去拉取一次广告数据并进行渲染，在此之后不再更新。如果想要展示其他内容的 BannerAd，需要创建新的 BannerAd 并将之前的 BannerAd 进行销毁。

如果不对废弃的 BannerAd 进行销毁，则会导致其上的事件监听器无法释放。当没有释放的 BannerAd 积累过多时，将会产生性能问题。

oldBannerAd.destroy()
let newBannerAd = ks.createBannerAd({
  // ...
})
newBannerAd.show()

# 广告定时刷新

Banner广告默认开启定时刷新，刷新间隔为30秒。

开发者也可以在创建Banner广告时传入adIntervals参数自定义刷新时间，adIntervals参数为数字类型，单位为秒。注意：自动刷新的间隔不能低于30秒，因此 adIntervals 的参数值必须大于或等于30。

let newBannerAd = ks.createBannerAd({
  adUnitId: 'xxxx',
  adIntervals: 30, // 自动刷新频率不能小于30秒
  // ...
})
newBannerAd.show()

# 相关API

接口	功能说明
ks.createBannerAd	获取Banner广告组件
BannerAd	Banner广告组件
BannerAd.destroy	销毁Banner广告实例
BannerAd.show	显示Banner广告
BannerAd.hide	显示Banner广告
BannerAd.onResize	取消监听Banner广告关闭事件
BannerAd.offResize	取消监听Banner广告关闭事件
BannerAd.onError	监听Banner错误事件
BannerAd.offError	取消监听Banner错误事件

# 广告接入注意事项

kwai在播放广告时会校验播放环境，国外线上无此问题，国内环境很难通过校验。在测试广告时，请确认如下操作：

测试广告的Kwai App为开发者后台的新版
测试广告的Kwai Id已添加到开发者后台白名单(Kwai Id添加方式详见开发者后台)

# 常见问题

测试广告时激励视频黑屏或插屏广告报错：

原因：Kwai Id未添加或已失效
解决：重新在开发者后台添加白名单等待生效，生效时间二十分钟左右

← 虚拟支付金币发放 →

# 广告

# 激励视频广告

# 功能介绍

# 显示/隐藏

# 监听用户关闭广告

# 相关API

# 插屏广告

# 功能介绍

# 显示/隐藏

# 监听用户关闭广告

# 相关API

# Banner广告

# 功能介绍

# 显示/隐藏

# 广告拉取成功与失败

# onResize

# 创建新的 BannerAd，销毁旧的 BannerAd

# 广告定时刷新

# 相关API

# 广告接入注意事项

# 常见问题