本文详细介绍如何快速集成 Agora Cocos Creator SDK,并在你自己的 app 里实现基础的视频互动直播。
Cocos Creator 2.3.4 或以上(本文界面描述基于 Cocos Creator 2.4.3)
操作系统与集成开发环境要求:
目标平台 | 操作系统版本 | 集成开发环境版本 |
---|---|---|
Android | Android 4.1 或以上 |
|
iOS | iOS 9.0 或以上 | Xcode 9.0 或以上 |
有效的 Cocos 账户和 Cocos App ID。
参考以下步骤创建一个 Cocos Creator 项目。
打开 Cocos Creator 项目,点击界面右侧的服务打开服务面板。
点击 AppID 后的 按钮并点击设定 Cocos AppID。
点击下拉框,选择一个游戏,并点击关联,将该游戏与你的项目关联。
向下滚动服务面板,找到并点击 Agora RTC。
点击 Agora RTC 后的开通服务按钮 ,仔细阅读弹窗内容,并点击确认开通。
在 Agora RTC 面板底部,选择 SDK 类型为 Video,并点击保存,即可获取 Agora Cocos Creator SDK。你可以在 Cocos Creator 的控件库 > 云组件中看到 AgoraVideoRender。
成功获取 SDK 后,Cocos Creator 会在你的 Cocos Creator 项目中自动添加获取设备权限的代码,你无需另行配置。
Cocos Creator 也会使用你的 Cocos Creator 账户为你自动注册 Agora 账户并创建 Agora 项目。你可以点击 Agora RTC 面板上的前往控制台,打开 Agora 控制台。
Agora 会给每个项目自动分配一个 App ID 作为项目唯一标识。
在 Agora 控制台的项目管理页面,找到你的项目,点击 App ID 右侧的 图标,即可获取项目的 App ID。
为提高项目的安全性,Agora 推荐使用 Token 对即将加入频道的用户进行鉴权。
为了方便测试,Agora 控制台提供生成 RTC 临时 Token 的功能。参考以下步骤获取 RTC 临时 Token:
testroom
,然后点击生成。后续调用 API 加入频道时,请确保填入的频道名与这里的频道名一致。现在,我们已经将 Agora Cocos Creator SDK 集成到项目中了。你可以根据需要创建组件脚本及场景,并将组件脚本添加到场景节点中。详见创建和使用组件脚本。
接下来我们要在 Script/HelloWorld.js
中调用 Agora Cocos Creator SDK 提供的核心 API 实现基础的视频互动直播功能,API 调用时序见下图。
在调用其他 Agora API 前,你需要初始化 Agora 引擎。你需要在该步骤中填入你在配置 Agora 项目时获取到的 Agora App ID。
调用 init
,传入获取到的 App ID,即可初始化 Agora 引擎。
你也可以根据需求,在初始化时注册想要监听的回调事件。如注册用户加入频道和离开频道的回调。
cc.Class({
...
onLoad: function () {
// 初始化 Agora 引擎。将 YOUR_APPID 替换为你 Agora 项目的 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);
},
...
});
初始化结束后,调用 setChannelProfile
,将频道场景设为互动直播。
如果想切换为其他场景,需要先调用 release
释放 Agora 引擎,然后调用 init
重新初始化 Agora 引擎,再调用 setChannelProfile
设置新的频道场景。
cc.Class({
...
onLoad: function () {
...
// 设置频道场景为直播场景。
agora.setChannelProfile(agora.CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING);
},
...
});
互动直播频道有两种用户角色:主播和观众,其中默认的角色为观众。
设置频道场景为互动直播后,你可以参考如下步骤设置用户角色:
在 Cocos Creator 中,进入控件库 > 内置控件,将 Toggle Group 组件添加到场景编辑器。你可以自行调整 Toggle 组件的显示位置。
在层级管理器中,你可以看到 toggleContainer 内包含三个 Toggle 组件,你需要删除多余的 Toggle 组件(例如 toggle3)。
在 HelloWorld.js
中,调用 setClientRole
,使用用户选择的角色进行传参。
cc.Class({
...
setClientRole: function (toggle, customEventData) {
// 设置用户角色。用户选择的角色会通过 customEventData 传入。
// customEventData 为 1 表示观众,对应的枚举值为 agora.CLIENT_ROLE_TYPE.CLIENT_ROLE_AUDIENCE。
// customEventData 为 2 表示主播,对应的枚举值为 agora.CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER。
agora.setClientRole(customEventData);
},
...
});
回到 Cocos Creator,选中 toggle1 组件,在右侧属性检查器中找到 Toggle > Check Events,添加一个点击事件。
将层级管理器面板上的 Canvas 添加到该点击事件的 cc.Node 属性框。在 cc.Node 属性框后的两个下拉框中依次选择场景(HelloWorld)和触发事件(setClientRole),并在 CustomEventData 中输入 1。
点击下方添加组件 > 渲染组件 > Label,在 toggle1 中添加一个 Label,并在 Label > String 中输入观众。``
按步骤 3、4、5 依次配置 toggle2。注意需在 toggle2 的 CustomEventData 中输入 2,并在 Label > String 中输入主播。
为使主播在互动直播前看到本地图像,你需要在加入频道前设置本地视图。参考以下步骤设置本地视图:
在 HelloWorld.js
中,调用 enableVideo
方法启用视频模块,并调用 startPreview
方法开启本地视频预览。
cc.Class({
...
onLoad: function () {
...
// 启用视频模块。
agora.enableVideo();
// 开启本地视频预览。
agora.startPreview();
},
...
});
在 Cocos Creator 中,进入控件库 > 云组件,将 AgoraVideoRender 添加到场景编辑器中。
添加成功后,你可以在资源管理器的 assets 中看到 cloud-component,里面包含 AgoraVideoRender.js
和 AgoraVideoRender.prefab
文件。
完成设置角色和本地视图后,你可以参考如下步骤加入频道:
在 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)。
视频直播中,不论你是主播还是观众,都应该看到频道中的所有主播。
远端主播成功加入频道后,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 中。
根据场景需要,如结束通话、关闭 app 或 app 切换至后台时,调用 leaveChannel
离开当前通话频道。
离开频道后,如果你想退出应用或者释放 Agora 引擎的内存,需调用 release
方法销毁 Agora 引擎。
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 引擎。
agora.release();
},
// 本地用户离开频道回调。
onLeaveChannel: function (stats) {},
...
});
我们建议你在连接 Android 或 iOS 真机后,构建并运行项目。详见打包发布原生平台。
以构建并运行 iOS 项目为例,你可以参考如下步骤:
build
文件夹。./jsb-link/frameworks/runtime-src/proj.ios_mac
路径下,找到你的 iOS 项目(例如 hello_world.xcworkspace
)并用 Xcode 打开。当成功开始视频互动直播时,主播可以看到自己的画面;观众可以看到主播的画面。
Q: 我设置了正确的发布路径,为什么收到了 xxx.o:No such file or directory
报错?
A: 导致该错误的原因是发布路径太长,你需要缩短发布路径,例如将发布路径修改为磁盘根目录下。
我们在 GitHub 上提供一个开源的视频通话示例项目 Agora-Cocos-Quickstart/CocosCreator,你可以结合该示例项目与本文示例代码实现视频互动直播。