实现视频通话
本文详细介绍如何快速集成声网 Cocos Creator SDK，并在你自己的 app 里实现基础的视频通话。
前提条件
Cocos Creator 2.3.4 或以上（本文界面描述基于 Cocos Creator 2.4.3）
操作系统与集成开发环境要求：
目标平台 操作系统版本 集成开发环境版本 Android Android 4.1 或以上 - Android Studio 3.0 或以上
- Android SDK API 16 或以上
- Android NDK 17 或以上
iOS iOS 9.0 或以上 Xcode 9.0 或以上 有效的 Cocos 账户和 Cocos App ID。
如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。
创建 Cocos Creator 项目
参考以下步骤创建一个 Cocos Creator 项目。
- 打开 Cocos Creator，进入新建项目面板。
- 选择你需要的示例模板（本文以 Hello World 模板为例）、选择项目存储路径并在存储路径中输入项目名称。
- 点击新建项目。
获取 SDK
打开 Cocos Creator 项目，点击界面右侧的服务打开服务面板。
点击 AppID 后的
按钮并点击设定 Cocos AppID。
点击下拉框，选择一个游戏，并点击关联，将该游戏与你的项目关联。
向下滚动服务面板，找到并点击 Agora RTC。
点击 Agora RTC 后的开通服务按钮
，仔细阅读弹窗内容，并点击确认开通。
在 Agora RTC 面板底部，选择 SDK 类型为 Video，并点击保存，即可获取声网 Cocos Creator SDK。你可以在 Cocos Creator 的控件库 > 云组件中看到 AgoraVideoRender。
成功获取 SDK 后，Cocos Creator 会在你的 Cocos Creator 项目中自动添加获取设备权限的代码，你无需另行配置。
Cocos Creator 也会使用你的 Cocos Creator 账户为你自动注册声网账户并创建声网项目。你可以点击 Agora RTC 面板上的前往控制台，打开声网控制台。
配置声网项目
1. 获取声网 App ID
声网会给每个项目自动分配一个 App ID 作为项目唯一标识。
在声网控制台的项目管理页面，找到你的项目，点击 App ID 右侧的 图标，即可获取项目的 App ID。
2. 获取声网临时 Token
为提高项目的安全性，声网推荐使用 Token 对即将加入频道的用户进行鉴权。
为了方便测试，声网控制台提供生成 RTC 临时 Token 的功能。参考以下步骤获取 RTC 临时 Token：
- 在控制台的项目管理页面，找到你的项目，点击配置。
- 在主要证书下面，点击生成临时音视频 token。
- 输入一个频道名，例如
testroom，然后点击生成。后续调用 API 加入频道时，请确保填入的频道名与这里的频道名一致。 - 点击复制图标，即可复制生成的临时 token。
基本流程
现在，我们已经将声网 Cocos Creator SDK 集成到项目中了。你可以根据需要创建组件脚本及场景，并将组件脚本添加到场景节点中。详见创建和使用组件脚本。
接下来我们要在 Script/HelloWorld.js 中调用声网 Cocos Creator SDK 提供的核心 API 实现基础的视频通话功能，API 调用时序见下图。
1. 初始化声网引擎
在调用其他声网 API 前，你需要初始化声网引擎。你需要在该步骤中填入你在配置声网项目时获取到的声网 App ID。
调用 init，传入获取到的 App ID，即可初始化声网引擎。
你也可以根据需求，在初始化时注册想要监听的回调事件。如注册用户加入频道和离开频道的回调。
cc.Class({
...
onLoad: function () {
// 初始化声网引擎。将 YOUR_APPID 替换为你声网项目的 App ID。
agora.init('YOUR_APPID');
agora.on('joinChannelSuccess', this.onJoinChannelSuccess, this);
agora.on('leaveChannel', this.onLeaveChannel, this);
agora.on('userJoined', this.onUserJoined, this);
agora.on('userOffline', this.onUserOffline, this);
},
...
});2. 设置本地视图
为使用户在通话前看到本地图像，你需要在加入频道前设置本地视图。参考以下步骤设置本地视图：
在
HelloWorld.js中，调用enableVideo方法启用视频模块，并调用startPreview方法开启本地视频预览。cc.Class({ ... onLoad: function () { ... // 启用视频模块。 agora.enableVideo(); // 开启本地视频预览。 agora.startPreview(); }, ... });在 Cocos Creator 中，进入控件库 > 云组件，将 AgoraVideoRender 添加到场景编辑器中。
添加成功后，你可以在资源管理器的 assets 中看到 cloud-component，里面包含AgoraVideoRender.js和AgoraVideoRender.prefab文件。
3. 加入频道
完成设置本地视图后，你可以参考如下步骤加入频道：
在 Cocos Creator 中，添加一个加入或离开频道按钮。进入控件库 > 内置控件，将 Button 组件添加到场景编辑器。
在层级管理器中点击 button > Background > Label，在属性检查器中找到 Label > String，将按钮显示内容修改为加入频道。
在
HelloWorld.js中，定义一个clickButton方法，设置点击按钮的事件。cc.Class({ ... // 设置点击按钮的行为。 // joined 为 true 表示已经加入频道，点击按钮后会调用 leaveChannel 离开频道。 // joined 为 false 表示已经离开频道，点击按钮后会调用 joinChannel 加入频道。 clickButton: function () { if (this.joined) { this.leaveChannel(); } else { this.joinChannel(); } }, ... });调用
joinChannel并填入 Token、频道名称和用户 ID。cc.Class({ ... joinChannel: function () { // 加入频道。 // 将 YOUR_TOKEN 替换为你生成的 Token。 // 将 CHANNEL_NAME 替换为你生成 Token 时使用的频道名称。 // 在 uid 中输入你的用户 ID。 agora.joinChannel('YOUR_TOKEN', 'CHANNEL_NAME', '', uid); }, ... });在
onJoinChannelSuccess回调中添加是否加入频道的判断逻辑，用于动态更改 button 组件的显示内容。注意你需要删除HelloWorld.js中对 Label 的原始定义：- 删除
properties中的text: 'Hello, World!'代码。 - 删除
onLoad方法中的this.label.string = this.text;代码。
cc.Class({ ... // 本地用户加入频道回调。 onJoinChannelSuccess: function (channel, uid, elapsed) { // 加入频道后，按钮的显示内容变为离开频道。 this.joined = true; this.label.string = '离开频道'; }, ... });- 删除
回到 Cocos Creator 的层级管理器中，点击 Canvas。在右侧属性检查器中找到 HelloWorld 组件脚本，将 button 组件的 Label 添加至该组件脚本中，便于动态修改按钮显示内容。
在层级管理器中点击 button，在右侧属性检查器中找到 Button > Check Events，添加一个点击事件。
将 Canvas 添加到该点击事件的 cc.Node 属性框，并在 cc.Node 属性框后的两个下拉框中依次选择场景（HelloWorld）和触发事件（clickButton）。
4. 设置远端视图
视频通话中，你应该看到频道中的所有用户。
远端用户成功加入频道后，SDK 会触发 onUserJoined 回调，该回调中会包含这个用户的 uid 信息。你可以参考如下步骤设置远端视图：
在
HelloWorld.js中，导入AgoraVideoRender云组件，用于渲染远端用户的视频。在onUserJoined和onUserOffline回调中，添加是否显示远端视频的判断逻辑。// 导入 AgoraVideoRender 云组件。 const AgoraVideoRender = require('AgoraVideoRender'); cc.Class({ ... properties: { ... // 添加远端视图。 target: { default: null, type: cc.Prefab } }, ... // 远端用户加入频道回调。该回调可获取远端用户的 uid。 onUserJoined: function (uid, elapsed) { if (this.remoteUid === undefined) { this.remoteUid = uid; // 添加一个 Prefab。 const render = cc.instantiate(this.target); // 将 AgoraVideoRender 组件的 uid 设为远端用户的 uid。 render.getComponent(AgoraVideoRender).uid = this.remoteUid; // 将 AgoraVideoRender 组件添加到场景中。 cc.director.getScene().addChild(render, 0, `uid:${this.remoteUid}`); // 设置远端视图大小。 render.setContentSize(160, 120); // 设置远端视图位置。 render.setPosition(300, 120); } }, // 远端用户离开频道回调。 onUserOffline: function (uid, reason) { if (this.remoteUid === uid) { // 远端用户离开频道时，将 uid 设置为 undefined。 cc.director.getScene().getChildByName(`uid:${this.remoteUid}`).destroy(); this.remoteUid = undefined; } }, ... });在 Cocos Creator 中，点击层级管理器中的 Canvas，在资源管理器中找到 assets > cloud-component > AgoraVideoRender > AgoraVideoRender.prefab，并将其添加至 Canvas 属性检查器的 HelloWorld > Target 中。
5. 离开频道
根据场景需要，如结束通话、关闭 app 或 app 切换至后台时，调用 leaveChannel 离开当前通话频道。
离开频道后，如果你想退出应用或者释放声网引擎的内存，需调用 release 方法销毁声网引擎。
cc.Class({
...
leaveChannel: function () {
// 离开频道。
agora.leaveChannel();
if (this.remoteUid !== undefined) {
// 移除远端视图。
cc.director.getScene().getChildByName(`uid:${this.remoteUid}`).destroy();
this.remoteUid = undefined;
}
// 离开频道后，按钮的显示内容为加入频道。
this.joined = false;
this.label.string = '加入频道';
// 销毁声网引擎。
agora.release();
},
// 本地用户离开频道回调。
onLeaveChannel: function (stats) {},
...
});运行项目
我们建议你在连接 Android 或 iOS 真机后，构建并运行项目。详见打包发布原生平台。
以构建并运行 iOS 项目为例，你可以参考如下步骤：
- 在 Cocos Creator 菜单栏点击项目 > 构建发布。
- 输入游戏名称（默认为 hello_world），选择 iOS 作为发布平台，设置发布路径，并点击构建。
- 完成构建后，点击发布路径右侧的打开按钮，打开
build文件夹。 - 在
./jsb-link/frameworks/runtime-src/proj.ios_mac路径下，找到你的 iOS 项目（例如hello_world.xcworkspace）并用 Xcode 打开。 - 在 Xcode 中，选择你的 iOS 设备，点击构建和运行按钮运行该项目。运行成功后，你可以看到你的视频画面。
- 如果想体验视频通话效果，你可以邀请一位朋友克隆 API-Examples-Web 项目到本地，在浏览器中打开
Demo/index.html文件，并输入相同的 App ID、频道名和临时 Token，加入同一频道与 iOS 端互通。
当成功开始视频通话时，用户可以看到自己和其他用户的画面。
常见问题
Q: 我设置了正确的发布路径，为什么收到了 xxx.o:No such file or directory 报错？
A: 导致该错误的原因是发布路径太长，你需要缩短发布路径，例如将发布路径修改为磁盘根目录下。
相关链接
我们在 GitHub 上提供一个开源的视频通话示例项目 Agora-Cocos-Quickstart/CocosCreator，你可以下载或查看源代码。
