chore(微信视频号): 优化微信视频号的配置及显示

2026-01-07 17:12:38 +08:00
parent de63cd4c6a
commit c7e9b497ae
3 changed files with 176 additions and 75 deletions
--- a/docs/WECHAT_CHANNEL_INTEGRATION.md
+++ b/docs/WECHAT_CHANNEL_INTEGRATION.md
@@ -33,60 +33,20 @@
 }
 ```

-### 2.2 微信视频号API权限
+### 2.2 微信视频号API权限与关联

-#### 2.2.1 开通视频号相关权限
+#### 2.2.1 权限说明

-1. **登录微信小程序后台**
-   - 访问 [微信公众平台](https://mp.weixin.qq.com/)
-   - 使用小程序管理员账号登录
+`wx.openChannelsActivity` API 是小程序的基础能力，不需要单独开通权限，但需要满足以下条件：

-2. **进入开发管理**
-   - 左侧菜单：开发 → 开发管理
-   - 进入「接口设置」页面
+- **跳转打开视频号视频**：无主体限制，基础库版本 2.19.2 及以上
+- **内嵌视频号视频**：
+  - 从基础库版本 2.25.1 至 2.31.1，小程序需与视频号视频相同主体或关联主体
+  - 从基础库版本 2.31.1 开始，非个人主体小程序可内嵌非同主体/关联主体视频号视频

-3. **开通视频号权限**
-   - 找到「视频号」相关接口，具体名称为「打开视频号内容」
-   - 点击「开通」按钮
-   - 阅读并同意相关协议
-   - 等待审核通过（通常为即时审核，无需人工审核）
+#### 2.2.2 小程序与视频号关联（可选）

-4. **权限开通失败处理**
-   - 确保小程序已发布上线
-   - 确保小程序未被处罚或限制
-   - 如仍无法开通，请联系微信公众平台客服
-
-#### 2.2.2 小程序后台配置相关权限
-
-1. **配置manifest.json**
-   在UniApp项目的 `manifest.json` 文件中，需要确保以下配置正确：
-   
-   ```json
-   "mp-weixin": {
-       "appid": "你的小程序appid",
-       "setting": {
-           "urlCheck": false,
-           "postcss": false,
-           "es6": true,
-           "minified": true
-       },
-       "usingComponents": true,
-       "requiredPrivateInfos": [],
-       "__usePrivacyCheck__": true,
-       "optimization": {
-           "subPackages": true
-       }
-   }
-   ```
-
-2. **小程序后台权限设置**
-   - 登录微信小程序后台
-   - 左侧菜单：设置 → 基本设置
-   - 向下滚动找到「服务内容声明」部分
-   - 确保已勾选「视频」相关服务内容
-   - 如有必要，上传相关资质证明
-
-#### 2.2.3 小程序与视频号关联
+虽然跳转打开视频号视频无主体限制，但如果需要内嵌非同主体视频号视频（基础库 2.31.1 以下），则需要关联小程序与视频号：

 1. **小程序管理员操作**
   - 登录微信小程序后台
@@ -110,7 +70,7 @@
   - 检查视频号名称或ID是否输入正确
   - 如超过24小时未确认，需要重新发送关联邀请

-#### 2.2.4 关联条件
+#### 2.2.3 关联条件

 - **小程序要求**：必须已经发布上线，未被处罚或限制
 - **视频号要求**：必须已经完成实名认证，状态正常
@@ -118,9 +78,9 @@
 - **权限要求**：关联操作需要小程序管理员和视频号管理员共同确认
 - **主体要求**：小程序和视频号的主体可以不同，但需要双方管理员确认

-#### 2.2.5 权限验证
+#### 2.2.4 功能验证

-完成关联后，可以通过以下方式验证权限是否开通：
+可以通过以下方式验证视频号功能是否可用：

 1. **在微信开发者工具中验证**
   - 在微信开发者工具中打开小程序
@@ -128,18 +88,17 @@
     ```javascript
     console.log('是否支持视频号API:', typeof wx !== 'undefined' && typeof wx.openChannelsActivity === 'function');
     ```
-   - 如果返回 `true`，则表示权限开通成功
+   - 如果返回 `true`，则表示API可用

 2. **在真机环境中验证**
   - 使用微信扫码打开小程序
   - 触发视频号相关功能
   - 检查是否能正常打开视频号内容

-3. **权限验证失败处理**
-   - 确认小程序是否已与视频号关联
-   - 确认视频号API权限是否已开通
-   - 检查微信小程序基础库版本是否支持视频号API（建议使用最新版本）
-   - 尝试重新关联视频号
+3. **功能验证失败处理**
+   - 检查微信小程序基础库版本是否满足要求（跳转打开需要 2.19.2+，内嵌打开需要 2.25.1+）
+   - 对于内嵌打开，检查主体是否满足要求或是否已关联
+   - 检查 `feedId` 等参数是否正确

 ## 3. 组件使用

@@ -208,12 +167,17 @@

 ## 4. 视频播放实现

+小程序提供两种打开视频号视频的方式：跳转打开和内嵌打开。
+
+### 4.1 跳转打开视频号视频
+
 组件内部使用微信小程序的 `wx.openChannelsActivity` API 来打开视频号内容：

 ```javascript
 if (typeof wx !== 'undefined' && wx.openChannelsActivity) {
    wx.openChannelsActivity({
        feedId: item.feedId, // 视频号内容ID，必填
+        finderUserName: item.finderUserName, // 视频号ID（可选）
        success: (res) => {
            console.log('打开视频号成功', res);
        },
@@ -234,30 +198,82 @@ if (typeof wx !== 'undefined' && wx.openChannelsActivity) {
 }
 ```

-### 4.1 API参数说明
+### 4.2 内嵌视频号视频
+
+从基础库 2.25.1 开始支持，小程序可以通过 `channel-video` 组件在小程序中内嵌视频号视频，且支持无弹窗跳转打开视频号对应视频，使用该组件时需注意：
+
+- 组件调用无资质要求
+- 暂不支持纯图片视频号内容
+
+```vue
+<!-- #ifdef MP-WEIXIN -->
+<channel-video
+  feed-id="{{feedId}}"
+  finder-user-name="{{finderUserName}}"
+  feed-token="{{feedToken}}"
+  bindenterfullscreen="enterFullscreen"
+  bindexitfullscreen="exitFullscreen"
+  binderror="videoError"
+></channel-video>
+<!-- #endif -->
+```
+
+### 4.3 API参数说明

 - **feedId**：视频号内容ID，必填，必须是有效的视频号内容ID
+- **finderUserName**：视频号ID，可选
+- **feedToken**：非同主体视频号视频的标识，从基础库 2.31.1 开始支持，非个人主体小程序可使用
 - **success**：调用成功的回调函数
 - **fail**：调用失败的回调函数
 - **complete**：调用完成的回调函数（无论成功或失败）

-### 4.2 错误码说明
+### 4.4 错误码说明

 | 错误码 | 说明 | 解决方案 |
 |--------|------|----------|
-| 40001 | 未授权 | 检查小程序是否与视频号关联，确认视频号API权限是否已开通 |
+| 40001 | 未授权 | 对于内嵌打开，检查主体是否满足要求或是否已关联 |
 | 40002 | 参数错误 | 检查feedId是否正确，确保是有效的视频号内容ID |
 | 40003 | 视频号内容不存在或已被删除 | 确认feedId对应的视频号内容是否仍然存在 |
 | 40004 | 系统错误 | 稍后重试，或联系微信公众平台客服 |

+### 4.5 获取参数方法
+
+1. **获取finderUserName（视频号ID）**
+   - 登录视频号助手
+   - 在首页可以查看自己的视频号ID
+
+2. **获取feedId（视频号内容ID）**
+   - 登录视频号助手
+   - 在「动态管理」模块可以复制自己发表的每个视频对应的feedId
+
+3. **获取feed-token（非同主体视频号视频标识）**
+   - 登录MP平台，在「设置-基本设置-隐私与安全」找到「获取视频号视频ID权限」，并将开关打开
+   - 移动端找到想要内嵌的视频号视频，并复制该视频的feed-token
+   - 注意：打开开关后24小时内生效，失效后需要再次打开开关；开关打开状态仅对当前操作者生效
+
+### 4.6 主体判断逻辑
+
+#### 主体信息查询
+小程序主体信息可通过小程序资料页-开发团队进行查询，视频号主体信息可通过视频号首页-认证进行查询。
+
+#### 主体判断逻辑
+- **跳转打开视频号视频**：无主体限制，基础库版本 2.19.2 及以上
+- **内嵌视频号视频**：
+  - 从基础库版本 2.25.1 至 2.31.1，小程序需与视频号视频相同主体或关联主体
+  - 从基础库版本 2.31.1 开始，非个人主体小程序可内嵌非同主体/关联主体视频号视频
+
+关联主体申请流程可以参考：https://kf.qq.com/faq/190726e6JFja190726qMJBn6.html
+
+
+
 ## 5. 注意事项

 ### 5.1 环境限制

 - 微信视频号API只能在微信小程序环境中使用，其他环境（如H5、App）不支持
- 需要在微信小程序后台配置相关权限
- 小程序需要与视频号进行关联
- 微信小程序基础库版本建议使用2.10.0及以上
+- 跳转打开视频号视频需要微信小程序基础库版本 2.19.2 及以上
+- 内嵌视频号视频需要微信小程序基础库版本 2.25.1 及以上
+- 小程序与视频号关联仅在需要内嵌非同主体视频号视频（基础库 2.31.1 以下）时需要

 ### 5.2 数据格式

@@ -281,17 +297,16 @@ if (typeof wx !== 'undefined' && wx.openChannelsActivity) {
 ### 6.1 视频无法播放

 - 检查 `feedId` 是否正确，确保是有效的视频号内容ID
- 确认小程序是否与视频号关联
- 确认小程序是否开通了视频号相关权限
- 检查微信小程序基础库版本是否支持视频号API
+- 检查微信小程序基础库版本是否满足要求（跳转打开需要 2.19.2+，内嵌打开需要 2.25.1+）
+- 对于内嵌打开，检查主体是否满足要求（基础库 2.31.1 以下需要相同主体或关联主体）
 - 检查视频号内容是否仍然存在（未被删除）

-### 6.2 权限开通失败
+### 6.2 功能不可用

- 确保小程序已发布上线
- 确保小程序未被处罚或限制
- 确认小程序管理员账号权限是否正确
- 如仍无法开通，请联系微信公众平台客服
+- 确认当前环境是否为微信小程序环境
+- 检查微信小程序基础库版本是否满足要求
+- 对于内嵌打开，检查主体条件是否满足
+- 检查 `feedId` 等参数是否正确

 ### 6.3 关联失败