# 实现音视频互动 (/zh-CN/realtime-media/rtc/get-started/quick-start/mini-program) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何建立一个简单的项目并使用声网小程序 SDK 实现基础的视频通话。 ## 前提条件 [#前提条件-6] 开始前,请确保你的开发环境满足如下条件: - 一个经过企业认证的微信小程序账号。在调试小程序 Demo 过程中,需要使用 live-pusher 和 live-player 组件。只有特定行业的认证企业账号才可以使用这两个组件。详见[小程序官网文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html)。 - 下载并安装最新版本的[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)。 - 参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)在控制台创建项目、获取 App ID 和临时 Token,并[开通小程序服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service#mini-program-service)。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致鉴权失败或无法加入频道。 ::: - 至少一台安装有微信 App 的移动设备。 :::info[信息] 在集成微信小程序组件之前,声网建议你先阅读[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)。 ::: ## 准备开发环境 [#准备开发环境] ### 1. 获取小程序组件权限 [#1-获取小程序组件权限] 在[微信公众平台](https://mp.weixin.qq.com/)的小程序**开发**选项中,切换到**接口设置**页签,打开**实时播放音视频流**和**实时录制音视频流**的开关。 ![打开音视频开关](https://web-cdn.agora.io/docs-files/1605069073929) ### 2. 配置服务器域名 [#2-配置服务器域名] 在小程序的开发设置里,将如下域名配到服务器域名里,其中 **request 合法域名**区域填入以 https 开头的域名;**socket 合法域名**区域填入以 wss 开头的域名。 如果你使用的 SDK 为 **v2.5.3** 或更高版本,你需要在 **request 合法域名**及 **socket 合法域名**中添加以下域名: ```shell wss://miniapp.agoraio.cn https://uap-ap-web-1.agora.io https://uap-ap-web-2.agoraio.cn https://uap-ap-web-3.agora.io https://uap-ap-web-4.agoraio.cn https://report-ad.agoralab.co https://rest-argus-ad.agoralab.co ``` ![添加域名](https://web-cdn.agora.io/docs-files/1638759333663) 如果你使用的 SDK 为 v2.4.6 或更低版本,你需要在 request 合法域名及 socket 合法域名中添加以下域名: ```shell wss://miniapp.agoraio.cn https://miniapp-1.agoraio.cn https://miniapp-2.agoraio.cn https://miniapp-3.agoraio.cn https://miniapp-4.agoraio.cn ``` ### 3. 创建小程序 [#3-创建小程序] 参考如下步骤创建一个新的小程序。 1. 打开**微信开发者工具**,然后按照屏幕提示扫码登录。 2. 完成登录后,点击小程序界面的 **+**。 3. 在弹出的**新建项目**界面中,依次填入小程序的**项目名称**、本地存储**目录**、小程序 **AppID**,然后点击**新建**。 成功创建小程序后,微信开发者工具的左侧会显示当前小程序的界面。你还可以点击**真机调试**,并扫描生成的二维码,在手机上进行体验。 ### 4. 添加微信小程序组件 [#4-添加微信小程序组件] 在微信小程序中实现音视频功能,需要使用微信的 live-player 组件和 live-pusher 组件。详见[微信小程序 API 说明](https://developers.weixin.qq.com/miniprogram/dev/api/)。 - live-player 组件 该组件用于实现微信小程序的实时音视频播放功能。开发者在创建该组件后,还需要在 js 文件中调用 API 接口对应的组件来实现该功能。声网小程序中,创建 `live-player` 的示例代码如下: ```javascript ``` - live-pusher 组件 该组件用于实现微信小程序的实时音视频录制功能。开发者在创建该组件后,还需要在 js 文件中调用 API 接口对应的组件来实现该功能。声网小程序中,创建 `live-pusher` 的示例代码如下: ```javascript ``` ### 5. 集成 SDK [#5-集成-sdk] 你可以通过下载压缩包或 npm 任一种方式集成小程序 SDK。 下载压缩包 通过 npm 集成 1. 下载[声网小程序 SDK](/zh-CN/realtime-media/rtc/reference/downloads) 并解压。 2. 将 SDK 包中的 **Agora_Miniapp_SDK_for_WeChat.js** 文件复制到你的小程序项目文件夹中。 3. 使用 `require` 将小程序 SDK 导入到你的项目中: ```javascript // ..Agora_Miniapp_SDK_for_WeChat.js 为你的 js 文件本地路径 const AgoraMiniappSDK = require('..Agora_Miniapp_SDK_for_WeChat.js'); ``` 如果你使用 v2.6.0 或更高版本的小程序 SDK 以及 1.02.1808300 或更高版本的[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html),可通过 npm 安装小程序 SDK。 1. 初始化项目。在你的项目根目录打开终端,运行以下命令: ```shell npm init ``` 完成后,打开你的项目文件夹中的 `package.json` 文件。在 `dependencies` 字段中添加 `agora-miniapp-sdk` 及版本号,设为 `latest` 即使用最新版本。 ```json { "name": "premium-miniapp", "version": "1.0.0", "description": "", "main": "app.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "dependencies": { "agora-miniapp-sdk": "latest" }, // 添加其他业务逻辑 } ``` 2. 安装依赖。在你的项目根目录打开终端,运行以下命令: ```shell npm install ``` 3. 构建 npm。在微信开发者工具中,从菜单栏选择**工具** > **构建 npm**。 4. 导入 SDK。使用 `require` 将小程序 SDK 导入到你的项目中: ```javascript const AgoraMiniappSDK = require("agora-miniapp-sdk"); ``` ## 实现音视频互动 [#实现音视频互动] 完成上述步骤后,你可以参考下图中的业务流程图,在你的项目中实现通话功能。 ![小程序通话流程](https://web-cdn.agora.io/docs-files/1675997572227) :::info[信息] -2301 和 -1307 是微信小程序 `live-player` 和 `live-pusher` 组件的状态码,表示网络断连,需要自行重启。详见微信小程序 [live-player](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html) 和 [live-pusher](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html) 组件文档。 ::: ### 1. 初始化客户端对象 [#1-初始化客户端对象] 调用 [`client.init`](/zh-CN/api-reference/rtc/mini-program/classes/client#init) 方法创建并初始化一个用于控制通话的客户端对象。你需要将 `APPID` 替换为你的声网项目的 App ID。详见[获取 App ID](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。 ```javascript // Callback 形式调用 let client = new AgoraMiniappSDK.Client(); client.init(APPID () => { Utils.log(`client init success`); }, e => { Utils.log(`client init failed: ${e} ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 let client = new AgoraMiniappSDK.Client(); await client.init(APPID) ``` ### 2. 加入频道 [#2-加入频道] 调用 [`client.join`](/zh-CN/api-reference/rtc/mini-program/classes/client#join) 方法加入频道。 在 `client.join` 中你需要将 `yourToken` 替换成你自己生成的 Token。并填入想要加入的频道名以及用户 `uid`。在测试阶段,你可以直接在控制台[生成临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。在生产环境,我们推荐你在自己的服务端生成 Token,详见在[服务端生成 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 ```javascript // Callback 形式调用 client.join(yourToken, channel, uid, () => { Utils.log(`client join channel success`); }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 await client.join(yourToken, channel, uid) ``` ### 3. 发布本地流 [#3-发布本地流] 成功加入频道后,就能调用 [`client.publish`](/zh-CN/api-reference/rtc/mini-program/classes/client#publish) 方法将本地音视频流发布到频道中。成功发布后,SDK 会返回该路音视频流的 URL。 ```javascript // Callback 形式调用 client.publish(url => { Utils.log(`client publish success`); resolve(url); }, e => { Utils.log(`client publish failed: ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 const url = await client.publish() ``` ### 4. 订阅远端流 [#4-订阅远端流] 当远端流发布到频道时,会触发 `stream-added` 事件,我们需要通过 [`client.on`](/zh-CN/api-reference/rtc/mini-program/classes/client#on) 监听该事件并在回调中订阅新加入的远端流。 ```javascript // Callback 形式调用 client.on("stream-added", e => { client.subscribe(uid => { Utils.log(`stream ${uid} subscribed successful`); }, e => { Utils.log(`stream subscribed failed ${e} ${e.code} ${e.reason}`); }); }); // Promise 形式调用 client.on("stream-added", async e => { const { url, rotation } = await client.subscribe(uid) }); ``` 当远端用户取消发布流或退出频道时,关闭及移除对应的流。 ```javascript client.on("stream-removed", e => { console.log(`stream-removed: ${JSON.stringify(e)}`) let uid = e.uid[0]; console.log(`stream ${uid} removed`); this.removeMedia(uid); }); ``` ### 5. 更多功能 [#5-更多功能] 在实际使用中,你还可以根据使用场景实现如下功能。 **重连** 如果你的项目中有切换到后台的场景需求,声网推荐调用 [`client.rejoin`](/zh-CN/api-reference/rtc/mini-program/classes/client#rejoin) 方法做好重连机制。你需要在该方法中传入当前频道内所有用户的 `uid` 作为额外参数。其他参数的设置与 `join` 方法相同。 ```javascript // Callback 形式调用 client.rejoin(yourToken, channel, uid, uids, () => { Utils.log(`client join channel success`); }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); }); // Promise 形式调用 await client.rejoin(yourToken, channel, uid, uids) ``` ### 完整示例代码 [#完整示例代码] 你可以直接参考如下示例代码,在项目中实现想要的功能。 ```javascript tab="以下为 callback 形式调用的完整示例代码" // 以下为 callback 形式调用的完整示例代码 let client = new AgoraMiniappSDK.client(); this.client = client; // 初始化客户端 client.init(APPID, () => { Utils.log(`client init success`); // 加入频道 client.join(yourToken, channel, uid, () => { Utils.log(`client join channel success`); // 发布本地流 if (this.isBroadcaster()) { client.publish(url => { Utils.log(`client publish success`); resolve(url); }, e => { Utils.log(`client publish failed: ${e.code} ${e.reason}`); reject(e) }); } else { resolve(); } }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); reject(e) }) }, e => { Utils.log(`client init failed: ${e} ${e.code} ${e.reason}`); reject(e) }); ``` ```javascript tab="以下为 promise 形式调用的完整示例代码" // 以下为 promise 形式调用的完整示例代码 try { let client = new AgoraMiniappSDK.client(); // 初始化客户端 await client.init(APPID) // 设置角色 this.role = "broadcaster" await client.setRole(this.role) // 加入频道 await client.join(yourToken, channel, uid) if (this.isBroadcaster()) { // 发布本地流 const url = await client.publish() } } catch (e) { console.error(e) } ``` ## 运行项目 [#运行项目] 为保证运行效果,我们建议你在真机上运行项目。完成开发后,点击**微信开发者工具**界面的**真机调试**。扫描生成的二维码,即可在手机端运行和调试项目。 ## 参考信息 [#参考信息-6] ### 与 Native 互通 [#与-native-互通] 频道中有小程序 SDK 和 Native SDK 时,可以选择如下一种方式实现互通: - Native 端在直播模式下,将用户角色设置为 `AgoraClientRoleBroadcaster` = 1:主播,实现互通 - Native 端在直播模式下,不设置用户角色为主播,也可以接收到小程序端的流,实现互通 小程序和 Native 互通时,Native 端视频画面可能出现上下颠倒。该问题可能是由于 Native SDK 中的 `setVideoEncoderConfiguration` 设置的方向模式 `orientationMode` 为 `ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE` 导致的。解决方法是,将方向模式改成 `ORIENTATION_MODE.ORIENTATION_MODE_FIXED_PORTRAIT` 就可以解决问题。 ### 与 Web 互通 [#与-web-互通] 小程序和 Web 互通时,可能出现 Web 端可以看到小程序的视频,但小程序看不到 Web 端的视频。该问题可能是由于编解码格式不被支持导致的。 Web 与小程序互通时,小程序端只支持 H264 模式的编码,不支持 VP8。将 Web SDK 的 `index.html` 文件修改为如下设置即可: ```javascript client = AgoraRtc.createClient({mode: "live", codec: "h264"}); ``` ### 示例项目 [#示例项目-6] 声网在 GitHub 上提供一个开源的小程序实时音视频示例项目,你可以下载体验或参考源代码。 ### 相关文档 [#相关文档-5] 使用微信小程序 SDK 开发过程中,你还可以参考如下文档: * [跑通小程序示例项目](/zh-CN/realtime-media/rtc/get-started/run-demo) * [小程序 SDK 常见问题集](/zh-CN/reference/faq/integration/mini_program):例如日志功能,通用问题,错误排查。 * [SDK 错误码和警告码](/zh-CN/realtime-media/rtc/reference/error-code)