文档

# 广告

Banner 广告组件是由客户端原生的图片、文本控件组成的原生组件，层级最高，会覆盖在上屏 Canvas 上。

开发者可以调用 qq.createBannerAd 创建 Banner 广告组件。Banner 广告组件在创建后会自动拉取广告数据并进行渲染，开发者只需要控制 Banner 广告组件的位置和显示/隐藏即可。

const bannerAd = qq.createBannerAd({
  adUnitId: "xxxx",
  style: {
    width: 320
  }
});

bannerAd.onResize(size => {
  // 底部居中显示
  bannerAd.style.top = windowHeight - size.height;
  bannerAd.style.left = (windowWidth - size.width) / 2;

  bannerAd
    .show()
    .then(() => {
      console.log("show ok");
    })
    .catch(res => {
      console.log("show error", res);
    });
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 显示/隐藏

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

bannerAd.show();
1

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

bannerAd.hide();
1

# 广告拉取成功与失败

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

bannerAd.onError(err => {
  console.log(err);
});
1
2
3

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

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

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

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

bannerAd.show().then(() => console.log("banner 广告显示"));
1
2
3
4
5

# onResize

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

const bannerAd = qq.createBannerAd({
  adUnitId: "xxxx",
  style: {
    left: 10,
    top: 76,
    width: 320
  }
});

bannerAd.show();
bannerAd.style.width = 400;
1
2
3
4
5
6
7
8
9
10
11

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

const { screenWidth } = qq.getSystemInfoSync();
1

当 style.width 小于 300 时，会取作 300。 当 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);
});
1
2
3
4

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

bannerAd.onResize(res => {
  bannerAd.style.width = res.width + Math.random() * 10;
});
1
2
3

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

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

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

oldBannerAd.destroy();
const newBannerAd = qq.createBannerAd({
  // ...
});
newBannerAd.show();
1
2
3
4
5

# 激励视频广告

激励视频广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在上屏 Canvas 上。

开发者可以调用 qq.createRewardedVideoAd 创建激励视频广告组件。该方法返回的是一个全局单例。

const video1 = qq.createRewardedVideoAd({ adUnitId: "xxxx" });
const video2 = qq.createRewardedVideoAd({ adUnitId: "xxxx" });
console.log(video1 === video2);
// true
1
2
3
4

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

const rewardedVideoAd = qq.createRewardedVideoAd({ adUnitId: "xxxx" });
1

为避免滥用广告资源，目前每个用户每天可观看激励式视频广告的次数有限，建议展示广告按钮前先判断广告是否拉取成功。

# 显示/隐藏

激励视频广告组件默认是隐藏的，需要调用 RewardedVideoAd.show() 进行显示。

bannerAd.show();
1

只有在用户点击激励视频广告组件上的 关闭广告 按钮时，广告才会关闭。开发者不可控制激励视频广告组件的隐藏。

# 广告拉取成功与失败

激励视频广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告，用户点击 关闭广告 后会去拉取下一条广告。

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

rewardedVideoAd.onLoad(() => {
  console.log("激励视频 广告加载成功");
});

rewardedVideoAd.show().then(() => console.log("激励视频 广告显示"));
1
2
3
4
5

如果拉取失败，通过 RewardedVideoAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档

rewardedVideoAd.onError(err => {
  console.log(err);
});
1
2
3

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

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

# 拉取失败，重新拉取

如果组件的某次自动拉取失败，那么之后调用的 show() 将会被 reject。此时可以调用 RewardedVideoAd.load() 手动重新拉取广告。

rewardedVideoAd.show().catch(err => {
  rewardedVideoAd.load().then(() => rewardedVideoAd.show());
});
1
2
3

如果组件的自动拉取是成功的，那么调用 load() 方法会直接返回一个 resolved Promise，而不会去拉取广告。

rewardedVideoAd.load().then(() => rewardedVideoAd.show());
1

# 监听用户关闭广告

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

RewardedVideoAd.onClose() 的回调函数会传入一个参数 res，res.isEnded 描述广告被关闭时的状态。

属性 类型 说明
isEnded boolean 视频是否是在用户完整观看的情况下被关闭的，true 表示用户是在视频播放完以后关闭的视频，false 表示用户在视频播放过程中关闭了视频

← PC 小游戏 →