jyj-components 1.0.2 → 1.0.3

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dir:*)",
+      "Bash(tree:*)",
+      "WebFetch(domain:developers.weixin.qq.com)"
+    ]
+  }
+}

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 秒。
+
+