jyj-components 1.0.2 → 1.0.4

package/README.md

@@ -1,72 +1,128 @@
 # 聚优甲广告组件库
 
-微信小程序广告组件库。
+微信小程序广告组件库，支持横幅广告、插屏广告、激励视频广告和开屏广告。
+
+## 目录
+
+- [安装](#安装)
+- [添加合法域名](#添加合法域名)
+- [组件使用](#组件使用)
+  - [横幅广告](#1-横幅广告-ad-banner)
+  - [插屏广告](#2-插屏广告-ad-interstitial)
+  - [激励视频广告](#3-激励视频广告-ad-rewarded-video)
+  - [开屏广告](#4-开屏广告-ad-splash)
+- [注意事项](#注意事项)
+- [常见问题](#常见问题)
 
 ## 安装
 
-### 方式一：npm 安装（推荐）
+### npm 安装（推荐）
 
 ```bash
 npm install jyj-components
 ```
 
-在小程序 `app.json` 中配置：
+#### 小程序原生项目配置
+
+参考[小程序npm支持](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)
+
+1. 小程序开发者工具 -> 详情(工具右上角) -> 本地设置 -> 使用npm模块
+2. 小程序开发者工具 -> 工具 -> 构建 npm
+3. 构建成功后小程序代码包中将产出 `miniprogram_npm` 文件夹
+
+#### uni-app 框架配置
+
+参考[小程序自定义组件支持](https://uniapp.dcloud.io/frame?id=%e5%b0%8f%e7%a8%8b%e5%ba%8f%e8%87%aa%e5%ae%9a%e4%b9%89%e7%bb%84%e4%bb%b6%e6%94%af%e6%8c%81)
+
+1. 在根目录新建 `wxcomponents` 文件夹
+2. 打开 `node_modules/jyj-components` 文件，**复制目录中整个 src 文件到 wxcomponents 目录下新建 jyj-components 文件夹**，按需重命名使用
 
-```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"
-  }
-}
-```
 
-### 方式二：本地引入
 
-将 `miniprogram_dist` 目录复制到项目中，然后在 `app.json` 中配置相对路径。
 
 ##  添加合法域名
 
-1. 小程序账号登录[微信公众平台](https://mp.weixin.qq.com/)
-2. 开发 —> 开发管理 —> 开发设置 —> 服务器域名
-3. 在 `downloadFile合法域名` 中增加如下配置
+1. 小程序账号登录 [微信公众平台](https://mp.weixin.qq.com/)
+2. 开发 → 开发管理 → 开发设置 → 服务器域名
+3. 在 `downloadFile合法域名` 中增加如下配置：
 
 ```
 https://wxgo.cdn.adwke.com
 ```
 
-4. 在request合法域名中增加
+4. 在 `request合法域名` 中增加：
 
 ```
-https://wxgo.adwke.com/
+https://wxgo.adwke.com
 ```
 
 ## 组件使用
 
-### 1. 横幅广告 (ad-banner)
+在使用广告的页面 json 配置文件中引入组件（按需配置）：
 
+```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 文件中使用：
 
 ```xml
 <ad-banner
   slotId="your-slot-id"
   bind:adLoad="onAdLoad"
   bind:adError="onAdError"
+  bind:adOpenMiniProgram="adOpenMiniProgram"
 />
 ```
 
-**属性：**
-- `slotId` (String, 必填)：广告位 ID
+**属性说明：**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| slotId | String | 是 | 广告位 ID |
+
+**事件说明：**
+
+| 事件名 | 说明 |
+|--------|------|
+| adLoad | 广告加载成功时触发 |
+| adError | 广告加载失败时触发 |
+| adOpenMiniProgram | 跳转小程序时触发 |
+
+在页面 js 文件中实现广告相关的事件回调函数：
+
+```javascript
+Page({
+  adOpenMiniProgram(options) {
+    wx.openEmbeddedMiniProgram({
+      appId: options.detail.appId,
+      path: options.detail.path,
+    });
+  },
+
+  onAdLoad(options) {
+    console.log('广告加载成功');
+  },
+
+  onAdError(options) {
+    console.log('广告加载失败', options);
+  }
+});
+```
 
-**事件：**
-- `adLoad`：广告加载成功
-- `adError`：广告加载失败
-- `adOpenMiniProgram`：跳转小程序（自定义广告）
 
 ### 2. 插屏广告 (ad-interstitial)
 
+在页面 wxml 文件中使用：
 
 ```xml
 <ad-interstitial
@@ -76,18 +132,28 @@ https://wxgo.adwke.com/
   bind:adLoad="onAdLoad"
   bind:adError="onAdError"
   bind:adClose="onAdClose"
+  bind:adOpenMiniProgram="adOpenMiniProgram"
 />
 ```
 
-**属性：**
-- `slotId` (String, 必填)：广告位 ID
-- `isShow` (Boolean)：控制广告显示
-- `isDestroy` (Boolean)：控制广告销毁 默认false 每个广告实例只能修改一次
+**属性说明：**
 
-**事件：**
-- `adLoad`：广告加载成功
-- `adError`：广告加载失败
-- `adClose`：广告关闭
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| slotId | String | 是 | - | 广告位 ID |
+| isShow | Boolean | 否 | false | 控制广告显示，需要广告加载成功后设置为 true 时展示插屏广告 |
+| isDestroy | Boolean | 否 | false | 控制广告销毁，每个广告实例只能修改一次 |
+
+> **注意：** 小程序打开后至少 20 秒才可以展示插屏广告，与其他插屏/激励视频广告展示间隔也是一样。
+
+**事件说明：**
+
+| 事件名 | 说明 |
+|--------|------|
+| adLoad | 广告加载成功时触发 |
+| adError | 广告加载失败时触发 |
+| adClose | 广告关闭时触发 |
+| adOpenMiniProgram | 跳转小程序时触发（自定义广告） |
 
 **使用示例：**
 
@@ -98,22 +164,35 @@ Page({
     destroyAd: false
   },
 
+  adOpenMiniProgram(options) {
+    wx.openEmbeddedMiniProgram({
+      appId: options.detail.appId,
+      path: options.detail.path,
+    });
+  },
+
+  // 显示插屏广告
   showInterstitialAd() {
     this.setData({ showAd: true });
   },
 
-  onAdClose() {
-    this.setData({
-      showAd: false,
-      destroyAd: true
-    });
+  onAdLoad(e) {
+    console.log('广告加载成功');
+  },
+
+  onAdError(e) {
+    console.log('广告加载失败', e);
+  },
+
+  onAdClose(e) {
+    console.log('广告关闭');
   }
 });
 ```
 
 ### 3. 激励视频广告 (ad-rewarded-video)
 
-
+在页面 wxml 文件中使用：
 
 ```xml
 <ad-rewarded-video
@@ -127,90 +206,165 @@ Page({
 />
 ```
 
-**属性：**
-- `slotId` (String, 必填)：广告位 ID
-- `isShow` (Boolean)：控制视频播放
-- `isDestroy` (Boolean)：控制广告销毁 默认false 每个广告实例只能修改一次
+**属性说明：**
 
-**事件：**
-- `adLoad`：广告加载成功
-- `adError`：广告加载失败
-- `adClose`：广告关闭
-- `adFinished`：视频播放完成（用户获得奖励）
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| slotId | String | 是 | - | 广告位 ID |
+| isShow | Boolean | 否 | false | 控制视频播放，当广告加载成功后设置为 true 时播放广告 |
+| isDestroy | Boolean | 否 | false | 控制广告销毁，每个广告实例只能修改一次 |
+
+**事件说明：**
+
+| 事件名 | 说明 |
+|--------|------|
+| adLoad | 广告加载成功时触发 |
+| adError | 广告加载失败时触发 |
+| adClose | 广告关闭时触发 |
+| adFinished | 视频播放完成时触发（用户获得奖励） |
 
 **使用示例：**
 
 ```javascript
 Page({
   data: {
-    showVideo: false
+    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)
 
+在小程序首页页面中使用：
 
 ```xml
-<ad-splash
-  slotId="your-slot-id"
-  bind:adLoad="onAdLoad"
-  bind:adError="onAdError"
-  bind:adFinished="onAdFinished"
-/>
+<block wx:if="{{showSplash}}">
+  <ad-splash
+    slotId="your-slot-id"
+    bind:adLoad="onAdLoad"
+    bind:adError="onAdError"
+    bind:adFinished="onAdFinished"
+  />
+</block>
 ```
 
-**属性：**
-- `slotId` (String, 必填)：广告位 ID
+**属性说明：**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| slotId | String | 是 | 广告位 ID |
 
-**事件：**
-- `adLoad`：广告加载成功
-- `adError`：广告加载失败
-- `adFinished`：广告结束（倒计时结束或用户跳过）
+**事件说明：**
+
+| 事件名 | 说明 |
+|--------|------|
+| adLoad | 广告加载成功时触发 |
+| adError | 广告加载失败时触发 |
+| adFinished | 广告结束时触发（倒计时结束或用户跳过） |
 
 **使用示例：**
 
 ```javascript
-// app.js 或首页
+// 首页 index.js
 Page({
+  data: {
+    showSplash: true
+  },
+
   onLoad() {
     // 开屏广告会自动展示
   },
 
-  onAdFinished() {
+  onAdLoad(e) {
+    console.log('开屏广告加载成功');
+  },
+
+  onAdError(e) {
+    console.log('开屏广告加载失败', e);
+    // 广告加载失败，直接进入主页面
+    this.setData({ showSplash: false });
+  },
+
+  onAdFinished(e) {
     // 广告结束，进入主页面
     console.log('开屏广告结束');
+    this.setData({ showSplash: false });
   }
 });
 ```
 
 ## 注意事项
 
-1. 向运营人员获取授权链接 通过授权链接授权权限
+1. **授权配置**：向运营人员获取授权链接，通过授权链接授权权限
 2. **广告位 ID**：需要向运营人员申请有效的 `slotId`
+3. **展示时机**：插屏广告和激励视频广告需要在小程序打开至少 20 秒后才能展示
+4. **广告间隔**：插屏广告、激励视频广告之间需要保持一定的展示间隔（至少 20 秒）
+5. **合法域名**：务必在微信公众平台配置合法域名，否则广告无法正常加载
 
 
 ## 常见问题
 
 ### Q: 广告不显示？
-A: 检查 `slotId` 是否正确，网络请求是否成功，广告数据格式是否正确。
+
+**A:** 请按以下步骤排查：
+1. 检查 `slotId` 是否正确
+2. 确认已在微信公众平台配置合法域名
+3. 检查网络请求是否成功（开发者工具 -> Network）
+4. 确认广告数据格式是否正确
+5. 检查是否已完成授权配置
 
 ### Q: 如何控制广告展示时机？
-A: 使用 `isShow` 属性控制插屏和激励视频的展示时机。
+
+**A:**
+- 横幅广告：组件加载后自动展示
+- 插屏广告和激励视频：使用 `isShow` 属性控制展示时机，在广告加载成功后设置为 `true`
+- 开屏广告：页面加载时自动展示
 
 ### Q: 如何销毁广告实例？
-A: 设置 `isDestroy` 为 `true` 即可销毁广告实例，释放内存。
+
+**A:** 设置 `isDestroy` 为 `true` 即可销毁广告实例，释放内存。注意每个广告实例只能销毁一次。
+
+### Q: 插屏广告和激励视频为什么无法立即展示？
+
+**A:** 根据微信小程序规范，插屏广告和激励视频广告需要在小程序打开至少 20 秒后才能展示，且两次广告展示之间需要间隔至少 20 秒。
+
+
 
 
 

package/miniprogram_dist/ad-banner/index.js

@@ -98,53 +98,159 @@ var _require = __webpack_require__(1),
     getAds = _require.getAds;
 
 module.exports = {
-  restoreAdState: function restoreAdState() {
+  // 检查并重置每日数据
+  checkAndResetDaily: function checkAndResetDaily() {
     var slotId = this.properties.slotId;
     var type = this.properties.type;
-    var adIndexKey = 'adIndex_' + slotId + '_' + type;
-    var adShowCountKey = 'adShowCount_' + slotId + '_' + type;
+    var dateKey = 'adDate_' + slotId + '_' + type;
 
-    var savedIndex = wx.getStorageSync(adIndexKey) || 0;
-    var savedShowCount = wx.getStorageSync(adShowCountKey) || 0;
+    var today = new Date().toDateString();
+    var savedDate = wx.getStorageSync(dateKey);
 
-    this.setData({
-      currentAdIndex: savedIndex,
-      currentAdShowCount: savedShowCount
-    });
+    // 如果日期不同，重置所有数据
+    if (savedDate !== today) {
+      var customAdIndexKey = 'customAdIndex_' + slotId + '_' + type;
+      var customAdShowCountKey = 'customAdShowCount_' + slotId + '_' + type;
+
+      wx.setStorageSync(dateKey, today);
+      wx.setStorageSync(customAdIndexKey, 1); // 自有广告从索引1开始
+      wx.setStorageSync(customAdShowCountKey, 0);
+
+      return true; // 表示已重置
+    }
+
+    return false; // 表示未重置
+  },
+  restoreAdState: function restoreAdState() {
+    // 检查并重置每日数据
+    this.checkAndResetDaily();
   },
   saveAdState: function saveAdState() {
     var slotId = this.properties.slotId;
     var type = this.properties.type;
-    var adIndexKey = 'adIndex_' + slotId + '_' + type;
-    var adShowCountKey = 'adShowCount_' + slotId + '_' + type;
+    var customAdIndexKey = 'customAdIndex_' + slotId + '_' + type;
+    var customAdShowCountKey = 'customAdShowCount_' + slotId + '_' + type;
+
+    // 只保存自有广告的状态（索引>0）
+    if (this.data.currentAdIndex > 0) {
+      wx.setStorageSync(customAdIndexKey, this.data.currentAdIndex);
+      wx.setStorageSync(customAdShowCountKey, this.data.currentAdShowCount);
+    }
+  },
+
+
+  // 检查微信广告是否失败（只在内存中，不持久化）
+  isWxAdFailed: function isWxAdFailed() {
+    return this.data.wxAdFailed || false;
+  },
+
+
+  // 标记微信广告失败（只在内存中，不持久化）
+  markWxAdFailed: function markWxAdFailed() {
+    this.setData({
+      wxAdFailed: true
+    });
+  },
+
+
+  // 检查所有自有广告是否都达到上限
+  isAllCustomAdsReachedLimit: function isAllCustomAdsReachedLimit() {
+    var ads = this.data.ads;
+    if (!ads || ads.length <= 1) return true; // 只有微信广告或没有广告
+
+    var currentIndex = this.data.currentAdIndex;
+    var showCount = this.data.currentAdShowCount;
+
+    // 如果当前不是自有广告，返回false
+    if (currentIndex === 0) return false;
+
+    // 找到最后一个有效的自有广告索引
+    var lastValidAdIndex = -1;
+    for (var i = ads.length - 1; i >= 1; i--) {
+      if (ads[i][this.properties.type] !== undefined) {
+        lastValidAdIndex = i;
+        break;
+      }
+    }
+
+    // 如果没有有效的自有广告，返回true
+    if (lastValidAdIndex === -1) return true;
+
+    // 如果当前索引已经是最后一个有效广告，且达到展示上限，返回true
+    if (currentIndex === lastValidAdIndex) {
+      var ad = ads[currentIndex];
+      var maxShowCount = ad.showCount || 1;
+      return showCount >= maxShowCount;
+    }
 
-    wx.setStorageSync(adIndexKey, this.data.currentAdIndex);
-    wx.setStorageSync(adShowCountKey, this.data.currentAdShowCount);
+    return false;
   },
   loadNextAd: function loadNextAd() {
     var ads = this.data.ads;
     if (!ads || ads.length === 0) return;
 
+    // 检查并重置每日数据
+    this.checkAndResetDaily();
+
     var currentIndex = this.data.currentAdIndex;
     var showCount = this.data.currentAdShowCount;
 
-    var currentAd = ads[currentIndex % ads.length];
+    // 如果是微信广告（索引0）且未失败，直接加载微信广告
+    if (currentIndex === 0 && !this.isWxAdFailed()) {
+      var wxAd = ads[0];
+      if (wxAd && wxAd[this.properties.type] !== undefined) {
+        this.setData({ currentAd: wxAd });
+        return;
+      } else {
+        // 微信广告没有配置，标记为失败，切换到自有广告
+        this.markWxAdFailed();
+        currentIndex = 1;
+        showCount = 0;
+      }
+    }
+
+    // 如果微信广告失败，从自有广告开始
+    if (currentIndex === 0 && this.isWxAdFailed()) {
+      // 从存储中恢复自有广告的状态
+      var slotId = this.properties.slotId;
+      var type = this.properties.type;
+      var customAdIndexKey = 'customAdIndex_' + slotId + '_' + type;
+      var customAdShowCountKey = 'customAdShowCount_' + slotId + '_' + type;
+
+      currentIndex = wx.getStorageSync(customAdIndexKey) || 1;
+      showCount = wx.getStorageSync(customAdShowCountKey) || 0;
+    }
+
+    // 如果没有自有广告，不展示任何广告
+    if (ads.length <= 1) {
+      return;
+    }
 
-    var maxShowCount = currentAd.showCount || 1;
+    // 检查所有自有广告是否都达到上限
+    if (this.isAllCustomAdsReachedLimit()) {
+      return;
+    }
+
+    // 处理自有广告的展示次数限制
+    var ad = ads[currentIndex];
+    var maxShowCount = ad.showCount || 1;
+
+    // 如果当前自有广告达到展示上限，切换到下一个
     if (showCount >= maxShowCount) {
       currentIndex = currentIndex + 1;
       showCount = 0;
-      this.setData({
-        currentAdIndex: currentIndex,
-        currentAdShowCount: showCount
-      });
-      this.saveAdState();
-    }
 
-    var ad = ads[currentIndex % ads.length];
-    this.setData({ currentAd: ad });
+      // 如果超出广告列表范围，说明所有广告都达到上限
+      if (currentIndex >= ads.length) {
+        return;
+      }
+
+      ad = ads[currentIndex];
+    }
 
+    // 检查当前广告是否有配置
     if (ad[this.properties.type] === undefined) {
+      // 没有配置，跳过并尝试下一个
       this.setData({
         currentAdIndex: currentIndex + 1,
         currentAdShowCount: 0
@@ -154,8 +260,11 @@ module.exports = {
       return;
     }
 
+    // 设置当前广告
     this.setData({
-      currentAdShowCount: showCount + 1
+      currentAd: ad,
+      currentAdIndex: currentIndex,
+      currentAdShowCount: showCount
     });
     this.saveAdState();
   },
@@ -179,8 +288,22 @@ module.exports = {
       this.triggerEvent('adLoad', e.detail || {});
     }
     this.report('load');
+
+    // 只有自有广告（索引>0）才增加展示计数
+    if (this.data.currentAdIndex > 0) {
+      var showCount = this.data.currentAdShowCount;
+      this.setData({
+        currentAdShowCount: showCount + 1
+      });
+      this.saveAdState();
+    }
   },
   adError: function adError(e) {
+    // 如果是微信广告（索引0）失败，标记为失败状态
+    if (this.data.currentAdIndex === 0) {
+      this.markWxAdFailed();
+    }
+
     if (e === 'undefined') {
       this.triggerEvent('adError', { msg: 'ad adError' });
     } else {
@@ -222,7 +345,13 @@ module.exports = {
               ads = _context.sent;
 
               this.setData({ ads: ads });
-              this.restoreAdState();
+
+              // 每次初始化时，总是从微信广告开始（索引0）
+              this.setData({
+                currentAdIndex: 0,
+                currentAdShowCount: 0
+              });
+
               this.loadNextAd();
 
             case 7:
@@ -312,7 +441,8 @@ Component({
     ads: [],
     currentAd: {},
     currentAdIndex: 0,
-    currentAdShowCount: 0
+    currentAdShowCount: 0,
+    wxAdFailed: false // 微信广告失败标记（仅内存，不持久化）
   },
   lifetimes: {
     attached: function () {
@@ -340,6 +470,18 @@ Component({
     }()
   },
   methods: {
+    checkAndResetDaily: function checkAndResetDaily() {
+      return adBase.checkAndResetDaily.call(this);
+    },
+    isWxAdFailed: function isWxAdFailed() {
+      return adBase.isWxAdFailed.call(this);
+    },
+    markWxAdFailed: function markWxAdFailed() {
+      adBase.markWxAdFailed.call(this);
+    },
+    isAllCustomAdsReachedLimit: function isAllCustomAdsReachedLimit() {
+      return adBase.isAllCustomAdsReachedLimit.call(this);
+    },
     restoreAdState: function restoreAdState() {
       adBase.restoreAdState.call(this);
     },
@@ -356,7 +498,8 @@ Component({
       adBase.adLoad.call(this, e);
     },
     adError: function adError(e) {
-      adBase.adError.call(this, e);
+      adBase.adError.call(this, e); // 先标记失败
+      this.loadNextAd(); // 再切换广告
     },
     adOpenMiniProgram: function adOpenMiniProgram() {
       adBase.adOpenMiniProgram.call(this);