聚优甲广告组件库

微信小程序广告组件库，支持横幅广告、插屏广告、激励视频广告和开屏广告。

目录

• 安装
• 添加合法域名
• 组件使用
  • 横幅广告
  • 插屏广告
  • 激励视频广告
  • 开屏广告
• 注意事项
• 常见问题

安装

npm 安装（推荐）

npm install jyj-components

小程序原生项目配置

参考小程序npm支持

1. 小程序开发者工具 -> 详情(工具右上角) -> 本地设置 -> 使用npm模块
2. 小程序开发者工具 -> 工具 -> 构建 npm
3. 构建成功后小程序代码包中将产出 miniprogram_npm 文件夹

uni-app 框架配置

参考小程序自定义组件支持

1. 在根目录新建 wxcomponents 文件夹
2. 打开 node_modules/jyj-components 文件，复制目录中整个 src 文件到 wxcomponents 目录下新建 jyj-components 文件夹，按需重命名使用

添加合法域名

1. 小程序账号登录 微信公众平台
2. 开发 → 开发管理 → 开发设置 → 服务器域名
3. 在 downloadFile合法域名 中增加如下配置：

https://wxgo.cdn.adwke.com

4. 在 request合法域名 中增加：

https://wxgo.adwke.com

组件使用

在使用广告的页面 json 配置文件中引入组件（按需配置）：

{
  "usingComponents": {
    "ad-banner": "jyj-components/ad-banner/index",
    "ad-interstitial": "jyj-components/ad-interstitial/index",
    "ad-rewarded-video": "jyj-components/ad-rewarded-video/index",
    "ad-splash": "jyj-components/ad-splash/index"
  }
}

1. 横幅广告 (ad-banner)

在页面 wxml 文件中使用：

<ad-banner
  slotId="your-slot-id"
  bind:adLoad="onAdLoad"
  bind:adError="onAdError"
  bind:adOpenMiniProgram="adOpenMiniProgram"
/>

属性说明：

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | slotId | String | 是 | 广告位 ID |

事件说明：

| 事件名 | 说明 | |--------|------| | adLoad | 广告加载成功时触发 | | adError | 广告加载失败时触发 | | adOpenMiniProgram | 跳转小程序时触发 |

在页面 js 文件中实现广告相关的事件回调函数：

Page({
  adOpenMiniProgram(options) {
    wx.openEmbeddedMiniProgram({
      appId: options.detail.appId,
      path: options.detail.path,
    });
  },

  onAdLoad(options) {
    console.log('广告加载成功');
  },

  onAdError(options) {
    console.log('广告加载失败', options);
  }
});

2. 插屏广告 (ad-interstitial)

在页面 wxml 文件中使用：

<ad-interstitial
  slotId="your-slot-id"
  isShow="{{showAd}}"
  isDestroy="{{destroyAd}}"
  bind:adLoad="onAdLoad"
  bind:adError="onAdError"
  bind:adClose="onAdClose"
  bind:adOpenMiniProgram="adOpenMiniProgram"
/>

属性说明：

| 属性 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | slotId | String | 是 | - | 广告位 ID | | isShow | Boolean | 否 | false | 控制广告显示，需要广告加载成功后设置为 true 时展示插屏广告 | | isDestroy | Boolean | 否 | false | 控制广告销毁，每个广告实例只能修改一次 |

注意： 小程序打开后至少 20 秒才可以展示插屏广告，与其他插屏/激励视频广告展示间隔也是一样。

事件说明：

| 事件名 | 说明 | |--------|------| | adLoad | 广告加载成功时触发 | | adError | 广告加载失败时触发 | | adClose | 广告关闭时触发 | | adOpenMiniProgram | 跳转小程序时触发（自定义广告） |

使用示例：

Page({
  data: {
    showAd: false,
    destroyAd: false
  },

  adOpenMiniProgram(options) {
    wx.openEmbeddedMiniProgram({
      appId: options.detail.appId,
      path: options.detail.path,
    });
  },

  // 显示插屏广告
  showInterstitialAd() {
    this.setData({ showAd: true });
  },

  onAdLoad(e) {
    console.log('广告加载成功');
  },

  onAdError(e) {
    console.log('广告加载失败', e);
  },

  onAdClose(e) {
    console.log('广告关闭');
  }
});

3. 激励视频广告 (ad-rewarded-video)

在页面 wxml 文件中使用：

<ad-rewarded-video
  slotId="your-slot-id"
  isShow="{{showVideo}}"
  isDestroy="{{destroyVideo}}"
  bind:adLoad="onAdLoad"
  bind:adError="onAdError"
  bind:adClose="onAdClose"
  bind:adFinished="onAdFinished"
/>

属性说明：

| 属性 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | slotId | String | 是 | - | 广告位 ID | | isShow | Boolean | 否 | false | 控制视频播放，当广告加载成功后设置为 true 时播放广告 | | isDestroy | Boolean | 否 | false | 控制广告销毁，每个广告实例只能修改一次 |

事件说明：

| 事件名 | 说明 | |--------|------| | adLoad | 广告加载成功时触发 | | adError | 广告加载失败时触发 | | adClose | 广告关闭时触发 | | adFinished | 视频播放完成时触发（用户获得奖励） |

使用示例：

Page({
  data: {
    showVideo: false,
    destroyVideo: false
  },

  // 观看视频获取奖励
  watchVideoForReward() {
    this.setData({ showVideo: true });
  },

  onAdLoad(e) {
    console.log('广告加载成功');
  },

  onAdError(e) {
    console.log('广告加载失败', e);
  },

  onAdClose(e) {
    console.log('广告关闭');
  },

  onAdFinished(e) {
    if (e.detail.isEnded) {
      // 用户看完视频，发放奖励
      console.log('用户看完视频，可以发放奖励');
      this.giveReward();
    } else {
      console.log('用户未看完视频');
    }
  },

  giveReward() {
    // 发放奖励的逻辑
    wx.showToast({
      title: '奖励已发放',
      icon: 'success'
    });
  }
});

4. 开屏广告 (ad-splash)

在小程序首页页面中使用：

<block wx:if="{{showSplash}}">
  <ad-splash
    slotId="your-slot-id"
    bind:adLoad="onAdLoad"
    bind:adError="onAdError"
    bind:adFinished="onAdFinished"
  />
</block>

属性说明：

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | slotId | String | 是 | 广告位 ID |

事件说明：

| 事件名 | 说明 | |--------|------| | adLoad | 广告加载成功时触发 | | adError | 广告加载失败时触发 | | adFinished | 广告结束时触发（倒计时结束或用户跳过） |

使用示例：

// 首页 index.js
Page({
  data: {
    showSplash: true
  },

  onLoad() {
    // 开屏广告会自动展示
  },

  onAdLoad(e) {
    console.log('开屏广告加载成功');
  },

  onAdError(e) {
    console.log('开屏广告加载失败', e);
    // 广告加载失败，直接进入主页面
    this.setData({ showSplash: false });
  },

  onAdFinished(e) {
    // 广告结束，进入主页面
    console.log('开屏广告结束');
    this.setData({ showSplash: false });
  }
});

注意事项

1. 授权配置：向运营人员获取授权链接，通过授权链接授权权限
2. 广告位 ID：需要向运营人员申请有效的 slotId
3. 展示时机：插屏广告和激励视频广告需要在小程序打开至少 20 秒后才能展示
4. 广告间隔：插屏广告、激励视频广告之间需要保持一定的展示间隔（至少 20 秒）
5. 合法域名：务必在微信公众平台配置合法域名，否则广告无法正常加载

常见问题

Q: 广告不显示？

A: 请按以下步骤排查：

1. 检查 slotId 是否正确
2. 确认已在微信公众平台配置合法域名
3. 检查网络请求是否成功（开发者工具 -> Network）
4. 确认广告数据格式是否正确
5. 检查是否已完成授权配置

Q: 如何控制广告展示时机？

A:

• 横幅广告：组件加载后自动展示
• 插屏广告和激励视频：使用 isShow 属性控制展示时机，在广告加载成功后设置为 true
• 开屏广告：页面加载时自动展示

Q: 如何销毁广告实例？

A: 设置 isDestroy 为 true 即可销毁广告实例，释放内存。注意每个广告实例只能销毁一次。

Q: 插屏广告和激励视频为什么无法立即展示？

A: 根据微信小程序规范，插屏广告和激励视频广告需要在小程序打开至少 20 秒后才能展示，且两次广告展示之间需要间隔至少 20 秒。