集成灵动会议
本文介绍如何将灵动会议集成到你的 Electron 项目中。
前提条件
开始前，请确保满足以下前提条件：
-
Node.js 18 或以上版本。
检查 Node.js 安装结果在终端输入以下命令检查 Node.js 是否安装成功：
Shellnode --version如果安装成功，终端会打印出版本信息，例如
v18.19.0。 -
可以访问互联网的计算机。确保你的网络环境没有部署防火墙，否则无法正常使用声网服务。
-
已开通灵动会议服务。
（可选）创建项目
如需创建一个新的 Electron 项目来集成灵动会议，在本地创建一个项目文件夹，并在文件夹下新建以下文件：
package.json：用于安装和管理项目依赖项。tsconfig.json：TypeScript 配置文件。main/bootstrap.ts：主进程文件。renderer/index.tsx：渲染进程文件。public/index.html：客户端页面文件。installer/icons/favicon.ico：Windows 应用图标。installer/icons/favicon.png：macOS 应用图标。installer/mac/entitlements.mac.plist：打包 macOS 应用所使用的entitlements文件。.env：用于构建项目的环境变量文件。
通过 npm 集成依赖
-
在项目的
package.json文件中添加以下依赖项：JSON{
"devDependencies": {
"electron": "24.8.8"
},
"dependencies": {
"fcr-ui-scene": "^3.1.0",
"agora-edu-core": "^3.1.0",
"agora-rte-sdk": "^3.1.0",
"agora-foundation": "^1.0.0",
"agora-ui-foundation": "^1.0.0",
"@electron/remote": "2.0.1",
"agora-electron-sdk": "4.3.2-build.90-rc.1",
"electron-screenshots": "^0.5.26",
"jszip": "^3.10.1"
}
}版本要求：
electron：当前仅支持 24.8.8 版本，不要修改成其他版本。fcr-ui-scene、agora-edu-core、agora-rte-sdk：均为灵动会议依赖库，当前支持 3.1.0 版本。如果灵动会议发布更新版本，你可以按需升级。
-
执行以下命令安装依赖：
Shellnpm install安装成功后，终端会打印如下信息：
Shell+ agora-toolchain@1.0.1-1
+ fcr-ui-scene@3.1.0
+ electron@24.8.8
+ agora-edu-core@3.1.0
+ agora-rte-sdk@3.1.0
+ agora-foundation@1.0.0
+ agora-ui-foundation@1.0.0
+ @electron/remote@2.0.1
+ agora-electron-sdk@4.3.2-build.90-rc.1
+ electron-screenshots@0.5.26
+ jszip@3.10.1
添加设备权限
如果你的开发目标平台为 Windows，则无需添加设备权限。
如果你的开发目标平台为 macOS，那么打包 macOS 应用时，你需要在 installer/mac/entitlements.mac.plist 文件中增加以下内容，以获取运行灵动会议所需权限。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- 允许即时编译（JIT） -->
<key>com.apple.security.cs.allow-jit</key>
<true/>
<!-- 允许未签名的可执行内存 -->
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<!-- 允许使用 dyld 环境变量 -->
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<true/>
<!-- 允许访问音频输入设备 -->
<key>com.apple.security.device.audio-input</key>
<true/>
<!-- 允许访问摄像头 -->
<key>com.apple.security.device.camera</key>
<true/>
</dict>
</plist>
启动灵动会议
本节介绍如何调用客户端 API 启动灵动会议。开始前，请确保已通过服务端 RESTful API 创建了房间。
-
在 Electron 主进程文件（例如
main/bootstrap.ts）中添加如下代码，以初始化 Electron 应用，挂载fcr-ui-scene钩子函数，创建并启动会议窗口。JavaScript// 引入 fcr-ui-scene/electron 模块
const { app, BrowserWindow } = require("electron");
const { initialize } = require("@electron/remote/main");
const { hookApp, hookWindow } = require("fcr-ui-scene/electron");
// 初始化 @electron/remote/main 模块
initialize();
// 将 fcr-ui-scene 的钩子函数挂载到 Electron 应用上
hookApp(app);
// 当 Electron 应用准备就绪时
app.addListener("ready", () => {
// 创建一个新的浏览器窗口
const browserWindow = new BrowserWindow({
webPreferences: {
nodeIntegration: true,
nodeIntegrationInWorker: true,
backgroundThrottling: false,
contextIsolation: false,
preload: require.resolve("fcr-ui-scene/lib/electron/preload.js"),
},
});
// 开启窗口远程模块访问
enable(browserWindow.webContents);
// 将钩子函数挂载到浏览器窗口
hookWindow(browserWindow);
// 加载打包后的 index.html 文件
browserWindow.loadFile("dist/index.html");
}); -
在渲染进程代码中引入
fcr-ui-scene模块，创建一个FcrUISceneCreator对象，并调用launch启动灵动会议。JavaScriptconst { FcrUISceneCreator } = require('fcr-ui-scene');
// 创建 FcrUISceneCreator 实例
const creator = new FcrUISceneCreator({
appId,
userId,
});
// 启动场景
const scene = creator.launch(
{
roomId,
roomToken,
userName,
userRole,
inviteLink
},
// 取消加入房间
() => {},
// 加入房间成功
(scene) => {},
// 加入房间失败
(error) => {},
// 要挂载的 DOM 节点
dom
);填写参数时可参考
FcrUISceneCreatorConfig和FcrUISceneConfig的 API 文档。需关注的核心参数如下：参数 类型 描述 appIdString 项目的 App ID。详见获取 App ID。 userIdString 用户 ID，是用户的唯一标识符，不可重复取值。长度在 64 字符以内。支持的字符集范围（共 36 个字符）：
- 26 个小写英文字母 a-z
- 10 个数字 0-9
roomTokenString 用于鉴权的 Token。详见控制台生成临时 Token 或服务端生成正式 Token。
注意临时 Token 仅适用于集成测试和体验。在生产环境中，请使用正式 Token 以确保安全。无论是临时 Token 还是正式 Token，有效期最长都是 24 小时，请尽快使用。
-
（可选）如需主动退出会议，调用
exit退出灵动会议。JavaScriptscene.exit();
（可选）构建和打包
本节介绍如何使用声网提供的 agora-toolchain 工具链进行项目构建和应用打包。如果你的项目已经使用了 Webpack、Electron-Builder 等构建工具，也可以自行配置相关命令。
操作步骤如下：
-
在项目的
package.json文件中添加以下配置：JSON{
"main": "dist/bootstrap.js",
"scripts": {
"bundle": "agora-tc-bundle --entry renderer/index && agora-tc-transpile --src main --out dist --transpile-only",
"build-electron-mac": "agora-tc-pack-app --platform darwin --arch x64 --main electron",
"build-electron-win": "agora-tc-pack-app --platform win32 --arch x64 --main electron",
"postinstall": "cp -r node_modules/agora-ui-foundation/patches/ patches/ && patch-package"
},
"devDependencies": {
"agora-toolchain": "^1.0.0"
}
}参数 描述 main代表 Electron 主进程的入口文件。 scripts包含各种构建和打包命令。 scripts.bundle用于构建项目中的页面代码和静态资源。 scripts.build-electron-mac用于打包 macOS 平台的项目客户端。 scripts.build-electron-win用于打包 Windows 平台的项目客户端。 scripts.postinstall用于拷贝补丁文件并为使用到的库打补丁。 agora-toolchain声网提供的工具链，用于构建和打包项目。 -
在
public/index.html文件中添加基本的 HTML 模板，作为项目的入口页面。html<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title><%= htmlWebpackPlugin.options.title %></title>
</head>
<body>
<div id="root" />
</body>
</html> -
在
.env文件中添加以下环境变量：Shellfcr_fragments=control-bar
fcr_fragment_plugins=multi-lang-plugin,css-preset-plugin
fcr_app_name=Meeting # 打包后的应用名称 -
执行以下命令构建项目代码：
Shellnpm run bundle构建产物会保存至
dist文件夹。构建成功后，终端会打印如下信息：ShellSuccessfully compiled 1 file with Babel. -
执行以下命令打包应用：
Shellnpm run build-electron-mac # 打包 macOS 应用
npm run build-electron-win # 打包 Windows 应用打包完成的应用会保存至
release文件夹。
日志文件路径
灵动会议默认的日志文件在如下目录中：
- macOS：
/Users/{your_system_user_name}/Library/Logs/{your_app_name}/logs/ - Windows 11 ：
C:\Users\{your_system_username}\AppData\Roaming\{your_app_name}\logs\logs\ - Windows 7 至 10：
C:\Users\{your_system_username}\AppData\Roaming\{your_app_name}\{your_app_name}\logs\logs\