广告

更新时间：2025-01-20 15:27:09

激励视频广告

功能介绍

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

激励视频广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在上屏 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	显示激励视频广告

插屏广告

iOS端插屏广告，竖屏游戏支持12.8.40及以上版本，横屏游戏支持12.11.30及以上版本

功能介绍

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

插屏广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在上屏 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))  

//iOS版本过低或者横屏游戏上调用show时会返回默认值
resolve({code: 1, msg: "iOS device return default value"})

监听用户关闭广告

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

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

相关API

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

Banner 广告

Banner 广告组件是由客户端原生的图片、文本控件组成的原生组件，层级最高，会覆盖在上屏 Canvas 上。Banner广告可生效版本，快手安卓版本>=12.10.30，iOS版本>=12.10.40，低版本需做兼容处理，横屏暂不支持。

开发者可以调用 ks.createBannerAd 创建 Banner 广告组件。Banner 广告组件在创建后，开发者调用show方法时拉取广告数据并进行渲染，开发者可以控制 Banner 广告组件的位置和显示/隐藏即可。

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

bannerAd.show()

显示/隐藏

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

bannerAd.show()

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

bannerAd.hide()

注意：避免Banner广告对玩家过多的打扰，当Banner广告在用户手动关闭之后，此次小游戏启动周期内不会再展示出banner广告。

广告拉取成功与失败

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

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

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

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

反之，如果拉取成功。BannerAd.onLoad 会执行，BannerAd.show 返回的 Promise 也会是一个 resolved Promise。两者的回调函数中都没有参数传递。

bannerAd.onLoad(() => {
  console.log('banner 广告加载成功')
})

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.top = 20
bannerAd.style.left = 20 //广告渲染完成之后，只允许改变广告的位置，宽高不再改变

Banner 广告组件的尺寸会根据开发者设置的宽度，即 style.width 进行等比缩放，缩放的范围是 308 到 屏幕宽度。屏幕宽度是以逻辑像素为单位的宽度，通过ks.getSystemInfoSync() 可以获取到。

let { screenWidth } = ks.getSystemInfoSync() 

当 style.width 小于 308 时，会取作 308。 当 style.width 大于屏幕宽度时，会取作屏幕宽度。 在组件内部会以此值为基准，根据 Banner 广告的标准尺寸，进行缩放。

每当缩放发生且缩放后的尺寸不同时，通过 BannerAd.onResize() 注册的回调函数就会执行。回调函数的参数是一个包含 BannerAd 缩放后的宽和高的对象。BannerAd 的 style.width 和 style.width 到经过缩放后的宽和高。

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

// 尺寸调整时会触发回调，通过回调拿到的广告真实宽高再进行定位适配处理
bannerAd.onResize((size) => {
  // good
  console.log(size.width, size.height);
  bannerAd.style.top = windowHeight - size.height;
  bannerAd.style.left = (windowWidth - size.width) / 2;
});

创建新的 BannerAd，销毁旧的 BannerAd

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

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

广告定时刷新

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

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

bannerAd.show()

相关接口

接口	功能说明
ks.createBannerAd	获取Banner广告组件
BannerAd	Banner广告组件
BannerAd.destroy	销毁Banner广告实例
BannerAd.offClose	取消监听Banner关闭事件
BannerAd.offError	取消监听Banner错误事件
BannerAd.onClose	监听Banner关闭事件
BannerAd.onError	监听Banner错误事件
BannerAd.show	显示Banner广告
BannerAd.hide	隐藏Banner广告
BannerAd.onResize	监听Banner广告大小事件
BannerAd.offResize	取消监听Banner广告大小事件
BannerAd.onLoad	监听Banner广告加载事件
BannerAd.offLoad	取消监听Banner广告加载事件

广告频控

为了避免游戏频繁弹出广告降低用户游戏体验，平台新增了广告频控策略，触发频控规则无法播放广告，具体规则如下所示：

• 游戏冷启动30s内不允许播放插屏广告和Banner广告，尝试播放会失败
• 尝试播放插屏广告时，会检查之前60s内用户是否在播放过任意类型广告（包含插屏、激励视频，不区分游戏），如果有则播放插屏广告会失败
• 激励视频广告没有设置播放时间间隔