加入白板房间

  • Web

更新时间

了解如何快速接入互动白板 SDK,完成环境准备、参数配置、示例运行和核心流程验证。

声网互动白板房间提供丰富的编辑工具,支持展示静态图片、动态 PPT、H5 课件等多种格式的文件,不同终端用户能在白板上实时展示想法,轻松实现多人互动协作。

本文介绍如何创建 Web 项目、加入白板房间,并接入多窗口、动态 PPT 和新教具。示例采用 npm 与 Vite,使用 TypeScript 编写浏览器端模块。

注意

由于浏览器的安全策略对除 127.0.0.1 以外的 HTTP 地址作了限制,声网互动白板 SDK 仅支持 HTTPS 协议或者 http://localhost(http://127.0.0.1) ,请勿使用 HTTP 协议部署你的项目。

技术原理

下图展示了加入声网互动白板房间的基本流程。

当你的 App 客户端请求加入互动白板房间时:

  1. 你的 App 服务端使用 SDK Token 向声网互动白板服务端发起创建房间的请求。
  2. 成功创建房间后,声网互动白板服务端向你的 App 服务端返回新建房间的房间 UUID。
  3. 你的 App 服务端使用房间 UUID 生成 room Token,并将房间 UUID 和 room Token 发送给 App 客户端。
  4. App 客户端使用从声网控制台获取的 AppIdentifier 初始化互动白板 SDK 实例。
  5. App 客户端调用 SDK 的方法并传入房间 UUID 和 room Token 以加入互动白板房间。

前提条件

创建 Web 项目

在项目目录执行以下命令,初始化 npm 项目并安装开发服务器:

Shell
npm init -y
npm install -D vite
mkdir -p scripts

创建以下目录结构;public 中的资源通过站点根路径访问:

Text
.
├── index.html
├── scripts
│   └── index.ts
└── public

将以下内容写入 index.html。容器必须有明确高度,浏览器模块在容器创建后加载:

HTML
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>互动白板</title>
  </head>
  <body style="margin: 0;">
    <div id="whiteboard" style="width: 100%; height: 100vh;"></div>
    <script type="module" src="/scripts/index.ts"></script>
  </body>
</html>

获取 SDK

安装本页示例使用的 SDK、窗口管理器、动态 PPT App 和教具插件:

Shell
npm install white-web-sdk@2.16.59 @netless/window-manager@1.0.25 @netless/app-slide@0.2.108 @netless/appliance-plugin@1.1.45

将步骤 3~7 的 TypeScript 代码依次放入同一个 scripts/index.ts。步骤 4~6 定义接入函数和注册 App,步骤 7 调用这些函数完成一次入房和插件初始化。

SDK 版本见发版说明。

实现步骤

先由业务服务端创建房间并生成 Room Token,再在浏览器端完成 SDK 初始化和接入。SDK Token 应保存在服务端,客户端只接收 Room Token。

1. 创建房间

在 App 客户端加入互动白板房间前,你需要在 App 服务端调用互动白板服务端 RESTful API 创建一个房间。详见创建房间(POST)。

请求示例

你可以使用以下 Node.js 脚本发送请求:

提示

使用 Node.js 发送 HTTP 请求前安装 request 模块。你可以运行 npm install request 安装。

JavaScript
var request = require("request");
var options = {
  method: "POST",
  url: "https://api.netless.link/v5/rooms",
  headers: {
    "token": "你的 SDK Token",
    "Content-Type": "application/json",
    "region": "cn-hz",
  },
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

如果方法调用成功,声网互动白板服务端将返回新建房间的信息,其中的 uuid 是房间的唯一标识,App 客户端加入房间时需要传入该参数。

响应示例

JSON
{
    "uuid": "4a50xxxxxx796b", // 房间的 UUID
    "teamUUID": "RMmLxxxxxx15aw",
    "appUUID": "i54xxxxxx1AQ",
    "isRecord": true,
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

2. 生成 Room Token

创建房间并获取新建房间的 uuid 后,你需要在 App 服务端生成 Room Token 并下发给 App 客户端。当 App 客户端加入房间时,声网互动白板服务端会使用该 Token 对其鉴权。

你可以通过以下方式在 App 服务端生成 Room Token:

下面以调用 RESTful API 的方式为例介绍如何生成 Room Token。

请求示例

你可以使用以下 Node.js 脚本发送请求:

信息

使用 Node.js 发送 HTTP 请求前安装 request 模块。你可以运行 npm install request 安装。

JavaScript
var request = require("request");
var options = {
  method: "POST",
  // 将 <房间的 UUID> 替换成你的房间 UUID
  url: "https://api.netless.link/v5/tokens/rooms/<房间的 UUID>",
  headers: {
    "token": "你的 SDK Token",
    "Content-Type": "application/json",
    "region": "cn-hz",
  },
  body: JSON.stringify({ lifespan: 3600000, role: "admin" }),
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

如果方法调用成功,声网互动白板服务端将返回生成的 Room Token。

响应示例

JSON
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token

3. 创建 WhiteWebSdk 实例

填写项目的 appIdentifier 和房间所属数据中心。多窗口使用 useMobXState=true:

TypeScript
import { WhiteWebSdk, ApplianceNames, type InvisiblePluginClass, type Room } from 'white-web-sdk';

const whiteWebSdk = new WhiteWebSdk({
  appIdentifier: 'APP_IDENTIFIER',
  region: 'cn-hz',
  useMobXState: true
});

4. 加入房间

准备入房函数,传入步骤 1、2 获取的房间 UUID、Room Token,以及本用户唯一的 uid。region 必须与创建房间时一致。

useMultiViews=true 启用多 View;窗口管理器和教具插件需在入房前通过 invisiblePlugins 注册,实际列表在步骤 7 传入。disableMagixEventDispatchLimit=true 用于多窗口的事件分发。

TypeScript
async function joinWhiteboard(
  invisiblePlugins: InvisiblePluginClass<string, any, any>[]
): Promise<Room> {
  return await whiteWebSdk.joinRoom({
    uuid: 'ROOM_UUID',
    roomToken: 'ROOM_TOKEN',
    uid: 'CLIENT_UID',
    region: 'cn-hz',
    isWritable: true,
    useMultiViews: true,
    disableMagixEventDispatchLimit: true,
    invisiblePlugins
  });
}

5. 接入多窗口

WindowManager 管理主白板与课件窗口。入房成功后调用 WindowManager.mount,将界面挂载到页面容器,并引入窗口样式。本示例由 Window Manager 绑定视图,无需再调用 room.bindHtmlElement。

TypeScript
import { WindowManager } from '@netless/window-manager';
import '@netless/window-manager/dist/style.css';

async function mountWindows(room: Room, supportAppliancePlugin = false) {
  const container = document.getElementById('whiteboard');
  if (!container) throw new Error('找不到白板容器');
  return await WindowManager.mount({
    room,
    container,
    cursor: true,
    supportAppliancePlugin
  });
}

同时接入步骤 7 的新教具时,传入 supportAppliancePlugin=true。窗口配置和页面控制见多窗口与课件控制。

6. 接入动态 PPT

安装的 @netless/app-slide 用于展示转换后的动态 PPT。在入房前调用 WindowManager.register 注册 Slide,这样新打开和房间中已存在的课件窗口都能加载 App 实现。

TypeScript
import AppSlide from '@netless/app-slide';

WindowManager.register({
  kind: 'Slide',
  src: AppSlide
});

async function openDynamicPpt(manager: WindowManager) {
  const appId = await manager.addApp({
    kind: 'Slide',
    options: {
      title: '教学课件.pptx',
      scenePath: '/slides/lesson-1'
    },
    attributes: {
      taskId: 'CONVERSION_TASK_UUID',
      url: 'https://convertcdn.netless.link/dynamicConvert'
    }
  });
  console.info('动态 PPT 窗口 ID:', appId);
  return appId;
}

业务服务端先完成动态 PPT 转换,taskId 使用转换任务 UUID,url 使用转换结果的资源地址前缀(不是 PPT 源文件地址,末尾不带 /)。scenePath 必须是以 / 开头的场景目录,同一房间内每个 App 使用不同目录。创建 App 需要可写权限;等待窗口挂载后再调用 addApp。注册实现是每个客户端的本地准备,addApp 创建的是房间内同步的实例,页面刷新或另一用户入房时不要重复插入同一课件。

addApp 返回 ID 不表示课件首帧和全部资源已加载。转换、展示与课件操作见展示文件。

7. 开启新教具

多窗口新教具通过 ApplianceMultiPlugin 接入。先准备同一插件版本的两份 Worker:

Shell
mkdir -p public/appliance-1.1.45
cp node_modules/@netless/appliance-plugin/dist/fullWorker.js public/appliance-1.1.45/
cp node_modules/@netless/appliance-plugin/dist/subWorker.js public/appliance-1.1.45/

注册不可见插件并完成入房,挂载支持新教具的窗口管理器,然后调用 ApplianceMultiPlugin.getInstance 初始化。以下代码放在步骤 3~6 的代码之后:

TypeScript
import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
import '@netless/appliance-plugin/dist/style.css';

async function startWhiteboard() {
  const room = await joinWhiteboard([
    WindowManager as unknown as InvisiblePluginClass<string, any, any>,
    ApplianceMultiPlugin
  ]);
  const manager = await mountWindows(room, true);
  const plugin = await ApplianceMultiPlugin.getInstance(manager, {
    options: {
      cdn: {
        fullWorkerUrl: '/appliance-1.1.45/fullWorker.js',
        subWorkerUrl: '/appliance-1.1.45/subWorker.js'
      },
      extras: { useBackgroundThread: true }
    }
  });

  // 入房并完成插件初始化后设置初始教具。
  room.setMemberState({ currentApplianceName: ApplianceNames.pencil });
  // 在业务“打开课件”按钮中调用 openDynamicPpt(manager)。
  // 返回实例供业务保存,避免刷新或重新入房时重复 addApp。
  return { room, manager, plugin };
}

startWhiteboard().then(({ room, manager, plugin }) => {
  // 保存实例并绑定业务按钮,例如按钮点击时调用 openDynamicPpt(manager)。
  console.info('白板与新教具已初始化', room, manager, plugin);
}).catch(console.error);

Web 通过上述注册、supportAppliancePlugin 和实例初始化启用新教具。插件提供 Pencil、Selector、Eraser、Shape、Text 等绘制与编辑能力,业务应用提供教具切换按钮。同一房间各端应一致启用新教具。

Worker 与主线程插件必须来自同一版本,站点需允许 Worker 加载。离开页面时先解除业务事件监听,等待 plugin.destroy(),再等待 manager.destroy() 和 room.disconnect()。教具配置、扩展功能、背景图及事件监听见教具插件介绍与启用。

运行项目

替换 AppIdentifier、房间 UUID、Room Token 和 uid 后,在项目目录启动开发服务器:

Shell
npx vite --host 127.0.0.1

访问终端显示的本地地址,成功入房后可在主白板书写。需要展示动态 PPT 时,填入已完成转换的任务信息,再通过业务按钮调用 openDynamicPpt(manager)。部署时使用 HTTPS。

配置远端参数

需要在入房前读取远端参数时,参见动态配置。地址在创建 SDK 前设置,本地显式参数优先;读取失败回退本地参数。