# 集成智能云会议 (/zh-CN/realtime-media/meeting/get-started/integrate-meeting/electron)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文介绍如何将智能云会议集成到你的 Electron 项目中。
## 前提条件 [#前提条件-2]
开始前,请确保满足以下前提条件:
- Node.js 18 或以上版本。
在终端输入以下命令检查 Node.js 是否安装成功:
```shell
node --version
```
如果安装成功,终端会打印出版本信息,例如 `v18.19.0`。
- 可以访问互联网的计算机。确保你的网络环境没有部署防火墙,否则无法正常使用声网服务。
- 已[开通智能云会议服务](/zh-CN/realtime-media/meeting/build/enable-service)。
## (可选)创建项目 [#可选创建项目-2]
如需创建一个新的 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 集成依赖 [#通过-npm-集成依赖]
1. 在项目的 `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 版本。如果智能云会议发布更新版本,你可以按需升级。
2. 执行以下命令安装依赖:
```shell
npm 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
```
## 添加设备权限 [#添加设备权限-1]
如果你的开发目标平台为 Windows,则无需添加设备权限。
如果你的开发目标平台为 macOS,那么打包 macOS 应用时,你需要在 `installer/mac/entitlements.mac.plist` 文件中增加以下内容,以获取运行智能云会议所需权限。
```xml
com.apple.security.cs.allow-jit
com.apple.security.cs.allow-unsigned-executable-memory
com.apple.security.cs.allow-dyld-environment-variables
com.apple.security.device.audio-input
com.apple.security.device.camera
```
## 启动智能云会议 [#启动灵动会议-2]
本节介绍如何调用客户端 API 启动智能云会议。开始前,请确保已通过[服务端 RESTful API](/zh-CN/api-reference/meeting/restful/api/create-room) 创建了房间。
1. 在 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");
});
```
2. 在渲染进程代码中引入 `fcr-ui-scene` 模块,创建一个 `FcrUISceneCreator` 对象,并调用 [`launch`](/zh-CN/api-reference/meeting/electron#launch) 启动智能云会议。
```javascript
const { 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`](/zh-CN/api-reference/meeting/electron#fcruiscenecreatorconfig) 和 [`FcrUISceneConfig`](/zh-CN/api-reference/meeting/electron#fcruisceneconfig) 的 API 文档。需关注的核心参数如下:
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `appId` | String | 项目的 App ID。详见[获取 App ID](/zh-CN/realtime-media/meeting/build/enable-service#获取-app-id)。 |
| `userId` | String | [integrate-meeting-electron-html-0-2-2 details](#table-slot-integrate-meeting-electron-html-0-2-2) |
| `roomToken` | String | [integrate-meeting-electron-html-0-3-2 details](#table-slot-integrate-meeting-electron-html-0-3-2) |
**integrate-meeting-electron-html-0-2-2 details**
用户 ID,是用户的**唯一标识符**,不可重复取值。长度在 64 字符以内。支持的字符集范围(共 36 个字符):
- 26 个小写英文字母 a~z
- 10 个数字 0-9
**integrate-meeting-electron-html-0-3-2 details**
用于鉴权的 Token。详见[控制台生成临时 Token](/zh-CN/realtime-media/meeting/build/enable-service#生成临时-token) 或[服务端生成正式 Token](/zh-CN/realtime-media/meeting/build/generate-token)。
:::warning[注意]
临时 Token 仅适用于集成测试和体验。在生产环境中,请使用正式 Token 以确保安全。无论是临时 Token 还是正式 Token,有效期最长都是 24 小时,请尽快使用。
:::
3. (可选)如需主动退出会议,调用 [`exit`](/zh-CN/api-reference/meeting/electron#exit) 退出智能云会议。
```javascript
scene.exit();
```
## (可选)构建和打包 [#可选构建和打包]
本节介绍如何使用声网提供的 `agora-toolchain` 工具链进行项目构建和应用打包。如果你的项目已经使用了 Webpack、Electron-Builder 等构建工具,也可以自行配置相关命令。
操作步骤如下:
1. 在项目的 `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` | 声网提供的工具链,用于构建和打包项目。 |
2. 在 `public/index.html` 文件中添加基本的 HTML 模板,作为项目的入口页面。
```html
<%= htmlWebpackPlugin.options.title %>
```
3. 在 `.env` 文件中添加以下环境变量:
```shell
fcr_fragments=control-bar
fcr_fragment_plugins=multi-lang-plugin,css-preset-plugin
fcr_app_name=Meeting # 打包后的应用名称
```
4. 执行以下命令构建项目代码:
```shell
npm run bundle
```
构建产物会保存至 `dist` 文件夹。构建成功后,终端会打印如下信息:
```shell
Successfully compiled 1 file with Babel.
```
5. 执行以下命令打包应用:
```shell
npm run build-electron-mac # 打包 macOS 应用
npm run build-electron-win # 打包 Windows 应用
```
打包完成的应用会保存至 `release` 文件夹。
## 日志文件路径 [#日志文件路径-2]
智能云会议默认的日志文件在如下目录中:
- 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\`