集成智能云会议

  • Electron

更新时间

了解如何快速接入智能云会议,完成环境准备、参数配置、示例运行和核心流程验证。

本文介绍如何将智能云会议集成到你的 Electron 项目中。

前提条件

开始前,请确保满足以下前提条件:

  • Node.js 18 或以上版本。

  • 可以访问互联网的计算机。确保你的网络环境没有部署防火墙,否则无法正常使用声网服务。
  • 已开通智能云会议服务。

(可选)创建项目

如需创建一个新的 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 集成依赖

  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

添加设备权限

如果你的开发目标平台为 Windows,则无需添加设备权限。

如果你的开发目标平台为 macOS,那么打包 macOS 应用时,你需要在 installer/mac/entitlements.mac.plist 文件中增加以下内容,以获取运行智能云会议所需权限。

XML
<?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 创建了房间。

  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 启动智能云会议。

    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 和 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 小时,请尽快使用。

表格内容超出当前宽度,可横向滚动查看更多列。
  1. (可选)如需主动退出会议,调用 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
    <!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>
  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 文件夹。

日志文件路径

智能云会议默认的日志文件在如下目录中:

  • 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\