qg.createBannerAd（横幅广告）

基础信息说明

功能概述：创建横幅（Banner）广告实例，支持显示/隐藏/销毁与事件订阅

<!--br {mso-data-placement:same-cell;}--> td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

参数说明

qg.createBannerAd(option)

• 未传 style 时由底层决定默认位置与尺寸（通常默认屏幕底部，尺寸变化通过 onResize 获取）。

style 结构说明

返回值说明

这是一个同步方法，调用后立即返回 BannerAd 实例。

BannerAd 对象方法与属性

横幅广告组件的尺寸会根据开发者设置的宽度，即 style.width 进行等比缩放，缩放的范围是designWidth * 50%到屏幕宽度。开发者在创建 BannerAd 时设置宽高，也可以在创建后设置，如：

 bannerAd.style.width = 1000

当 style.width 小于 designWidth * 50% 时，会取作 designWidth * 50%。当 style.width 大于屏幕宽度时，会取作屏幕宽度。 在组件内部会以此值为基准，根据 Banner 广告的标准尺寸，进行缩放。
每当缩放发生且缩放后的尺寸不同时，通过 BannerAd.onResize() 注册的回调函数就会执行。回调函数的参数是一个包含 BannerAd 缩放后的宽和高的对象。BannerAd 的 style.realWidth 和style.realHeight 到经过缩放后的宽和高

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

监听/取消监听事件方法

回调结果说明

回调成功

尺寸缩放与 onResize：

• Banner广告尺寸会根据开发者设置的宽度进行等比缩放，缩放的范围是 300 到 屏幕宽度;
• 事件的返回参数中包含真实的宽、高，若宽高不符合需求，可以动态的通过style.width设置改变广告的大小;
• 注意：如果在 onResize 的回调函数中重设 width 且总是与上一次缩放后的 width 不同，那么可能会导致 onResize 的回调函数一直触发，卡死在 onResize 的回调函数中。

回调失败

• onError：Banner 加载或展示流程中发生错误，常见回调形态：{ errMsg: string, errCode?: number }（以底层返回为准）。
• show()：Promise 的 reject(err) 为底层 fail 透传的错误对象或字符串。

示例代码

// 创建 Banner 广告
const bannerAd = qg.createBannerAd({
  adUnitId: 'test-banner-id',
  style: { left: 0, top: 0, width: 320 }
})

// 展示与隐藏
bannerAd
  .show()
  .then(() => console.log('banner 显示成功'))
  .catch(err => console.error('banner 显示失败', err))

// 业务需要时隐藏与销毁
bannerAd.hide()
bannerAd.destroy()

注意事项

• 请在不需要展示时调用 hide()，并在退出场景或页面时调用 destroy() 释放资源。

qg.createInterstitialAd（插屏广告）

基础信息说明

功能概述：创建插屏广告实例，支持展示与事件订阅（加载、错误、关闭、点击）

参数说明

qg.createInterstitialAd(option)

返回值说明

这是一个同步方法，调用后立即返回 InterstitialAd 实例。

InterstitialAd 对象方法与属性

监听/取消监听事件方法

回调结果说明

回调成功

回调失败

• onError：加载或展示流程中发生错误，常见回调形态：{ errMsg: string, errCode?: number }。
• show()：Promise 的 reject(err) 为底层 fail 透传的错误对象或字符串。

示例代码

// 创建插屏广告
const interstitialAd = qg.createInterstitialAd({ adUnitId: 'test-interstitial-id' })

// 事件订阅
interstitialAd.onLoad(() => {
  console.log('插屏加载成功')
})
interstitialAd.onError(err => {
  console.error('插屏错误', err)
})
interstitialAd.onClose(res => {
  console.log('插屏关闭', res)
})
interstitialAd.onClick(res => {
  console.log('插屏点击', res)
})

// 展示
interstitialAd
  .show()
  .then(() => console.log('插屏展示成功'))
  .catch(err => console.error('插屏展示失败', err))

注意事项

• 失败形态通常通过 onError 或 show() 的 reject(err) 返回，内容依底层实现。

qg.createRewardedVideoAd（激励视频广告）

基础信息说明

功能概述：创建激励视频广告实例，支持展示/加载与事件订阅（加载、错误、关闭、点击）

注意：版本兼容与调用选择

• 激励视频广告 与 激励广告说明：
  
• 激励视频广告：面向低版本，能力同本文接口说明。
• 激励广告（最小支持引擎版本 1307+）：在 13070201 以下框架版本不支持“激励广告”，请开发者做好兼容处理，改用“激励视频”。

• 统一接口：均使用 qg.createRewardedVideoAd(option)；若框架版本较低，可能不会下发“激励广告”，请优先按本文的“激励视频广告”说明实现，并在版本判断后再进行调用。

版本判断示例（以平台返回为准）：

//请根据以下方法获取到框架版本号之后判断选择调用的广告接口，激励广告/激励视频广告
//低版本调用激励广告接口不会下发广告
qg.getSystemInfo({
  success: info => {
    //可以获取框架版本前四位，如1307。
    console.log(info)
  }
})

参数说明

qg.createRewardedVideoAd(option)

返回值说明

这是一个同步方法，调用后立即返回 RewardVideoAd 实例。

RewardVideoAd 对象方法与属性

激励视频广告组件是一个全局单例，多次调用 qg.createRewardedVideoAd() 会复用同一个实例。该实例仅对当前页面有效，不允许跨页面使用。

监听/取消监听事件方法

回调结果说明

回调成功

关闭事件说明（重要）：

• onClose 回调参数中包含 isEnded 字段（类型：boolean），用于判断用户是否完整观看了激励视频广告
• isEnded 为 true 时表示视频是在用户完整观看的情况下被关闭的，可以发放奖励
• isEnded 为 false 时表示用户提前关闭了视频，不应发放奖励

发放奖励建议：仅当 isEnded === true 时发放；并结合业务侧二次校验（如服务端验证）提升安全性。

回调失败

• onError：加载或展示流程中发生错误；常见回调形态：{ errMsg: string, errCode?: number }（以底层返回为准）。
• show()：Promise 的 reject(err) 为底层 fail 透传的错误对象或字符串。
• load()：Promise 的 reject(err) 为底层 fail 透传的错误对象或字符串。

示例代码

// 创建激励视频广告
let rewardedVideoAd = qg.createRewardedVideoAd({
  adUnitId: 'xxxx'
})

// 事件订阅
rewardedVideoAd.onLoad(() => {
  console.log('激励视频加载成功')
  // 注意：请勿在onLoad回调中调用show()
})

rewardedVideoAd.onError(err => {
  console.error('激励视频错误', err)
  // err 包含 errMsg (String) 和 errCode (Number)
})

rewardedVideoAd.onClose(res => {
  console.log('激励视频关闭', res)
  // res.isEnded 为 boolean 类型，表示视频是否是在用户完整观看的情况下被关闭的
  if (res.isEnded) {
    console.log('用户完整观看，发放奖励')
    // 发放奖励逻辑
  } else {
    console.log('用户提前关闭，不发放奖励')
  }
})

// 1300+ 版本支持
rewardedVideoAd.onClick(res => {
  console.log('激励视频点击', res)
})

// 手动加载广告
rewardedVideoAd
  .load()
  .then(() => console.log('激励视频加载成功'))
  .catch(err => console.error('激励视频加载失败', err))

// 展示激励视频广告（广告将从屏幕下方推入）
rewardedVideoAd
  .show()
  .then(() => console.log('激励视频展示成功'))
  .catch(err => console.error('激励视频展示失败', err))

注意事项

• 请根据 onClose 回调中的 isEnded 字段（boolean 类型）判断是否发放奖励，建议只有 isEnded 为 true 时才发放奖励。

qg.createCustomAd（原生模板广告）

基础信息说明

功能概述：创建原生模板广告实例，支持展示/隐藏、销毁与事件订阅（加载、错误、尺寸变化、关闭、点击、展示）；支持通过 style 读写定位与大小。

参数说明

qg.createCustomAd(option)

style 的结构

返回值说明

这是一个同步方法，调用后立即返回 CustomAd 实例。

CustomAd 对象方法与属性

• 模板广告非全局单例，可按需创建多个实例，但建议控制数量并在不使用时及时销毁。
• customAd.style 可读写，支持在创建后动态调整尺寸与位置。
• 当 style.width 大于屏幕宽度时，实际展示将按屏幕宽度进行裁剪或限制。
• 未设置位置时，模板广告默认在屏幕底部展示（以平台实现为准）。

监听/取消监听事件方法

回调结果说明

回调成功

• 两个阶段：加载与展示，加载成功会触发 onLoad，展示完成会触发 onShow。
• 展示结果：调用 show() 返回 Promise，成功 resolve(data)，失败 reject(err)，失败也会触发 onError 事件。
• 隐藏广告：调用 hide() 隐藏模板广告。
• 资源释放：调用 destroy() 销毁实例，释放资源。

回调失败

• onError：加载或展示流程中发生错误；常见回调形态：{ errMsg: string, errCode?: number }（以底层返回为准）。
• show()：Promise 的 reject(err) 为底层 fail 透传的错误对象或字符串。

示例代码

// 创建原生模板广告
const customAd = qg.createCustomAd({
  adUnitId: 'xxx',
  style: {
    left: 0,
    top: 800,
    width: 1080
  }
})

// 事件订阅
customAd.onLoad(() => {
  console.log('模板广告加载完成')
})

customAd.onError(err => {
  console.error('模板广告错误', err)
  // err 包含 errMsg (String) 和 errCode (Number)
})

// 展示模板广告
customAd
  .show()
  .then(() => console.log('模板广告展示成功'))
  .catch(err => console.error('模板广告展示失败', err))

// 隐藏模板广告
customAd.hide()

注意事项

• 模板广告为原生组件，层级最高，会覆盖在普通组件上。
• 模板广告非单例，避免同时创建过多实例，及时调用 destroy() 释放资源。
• 版本要求：原生模板最小支持引擎版本 1110+，versionCode >= 11100001，点击事件 onClick 能力在 1300+ 可用。