2024/10/28 14:44:43

加入白板房间

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

本文介绍如何建立一个简单的项目，使用声网互动白板 SDK 加入房间并实现基础的白板功能。

注意

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

技术原理

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

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

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

前提条件

满足最低版本要求的浏览器。
有效的声网开发者账号。
已在声网控制台开启互动白板服务并获取白板项目的 AppIdentifer 和 SDK Token。
Node.js 及 npm。

服务端实现

在 App 客户端加入互动白板房间前，你需要在 App 服务端调用声网互动白板提供的 RESTful API 创建房间、获取 room UUID 和生成 room Token，并将 room UUID 和 room Token 传给 App 客户端。

注意

你需要自行实现将 room UUID 和 room Token 下发给 App 客户端的逻辑。

1. 创建房间

调用互动白板服务端 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：

使用代码生成 Room Token，详见在 App 服务端生成 Token。（推荐）
调用互动白板服务端 RESTful API 生成 Room Token，详见生成 Room Token（POST）。

下面以调用 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

客户端实现

创建一个名为 fastboard_quickstart 的文件夹。一个 Web 客户端项目至少需包含以下文件：

package.json: 安装并管理项目依赖。
index.html: 用于设计 Web 应用的用户界面。
main.js: 实现具体应用逻辑的代码。

1. 添加依赖项

参考如下步骤创建 package.json 文件并添加必要的依赖项：

进入 fastboard_quickstart 目录并运行 npm init 命令来创建 package.json 文件。
运行如下命令安装最新版本的 Fastboard SDK 及相关依赖项：
Shell
```
npm add @netless/fastboard @netless/window-manager white-web-sdk
```
各字段的含义如下：
- @netless/fastboard：Fastboard SDK。
- @netless/window-manager：窗口管理插件，用于实现和管理多窗口应用。
- white-web-sdk：提供互动白板核心功能的 SDK。

为运行和打包项目，你需要指定构建工具。本文使用 Vite。在 devDependencies 中添加 vite字段，并在 scripts 中定义项目运行的命令行。

JSON
{
    "name": "fastboard_quickstart",
    "private": true,
    "scripts": {
        "build": "vite build",
        "dev": "vite --open"
    },
    "dependencies": {
        "@netless/fastboard": "latest",
        "@netless/window-manager": "latest",
        "white-web-sdk": "latest"
    },
    "devDependencies": {
        "vite": "latest"
    }
}

2. 实现用户界面

将以下代码复制到 index.html 实现应用的用户界面：

html
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
</head>

<body>
    <div id="app" style="width: 600px; height: 400px; border: 1px solid;"></div>
    <script type="module" src="/main.js"></script>
</body>

</html>

注意

请确保给挂载白板的元素设置宽和高，否则无法看到白板页面。

3. 实现加入房间

调用 Fastboard SDK 的如下方法加入白板房间：

调用 createFastboard 创建一个 FastboardApp 实例并加入白板房间。
调用 mount 将 FastboardApp 实例挂载到网页元素中。

调用 createFastboard 方法时，你需要填入以下参数：

在 sdkConfig 中传入 SDK 配置参数：
- appIdentifier: 互动白板项目的 AppIdentifier。详见获取 AppIdentifier。
- region：数据中心，必须和创建房间时设置的数据中心一致。
在 joinRoom 中传入房间配置参数：
- uid: 用户的唯一标识符，字符串格式，长度不能超过 1024 字节。
- uuid: 房间 UUID，即房间的唯一标识符。详见创建房间。
- roomToken: 用于鉴权的 Room Token。生成该 Room Token 使用的房间 UUID 必须和上面的房间 UUID 一致。详见生成 Room Token。

将以下代码复制到 main.js 实现加入白板房间的逻辑：

JavaScript
import { createFastboard, mount } from "@netless/fastboard";
 
let app;
async function mountFastboard(div) {
  app = await createFastboard({
    sdkConfig: {
      appIdentifier: "你的 AppIdentifier",
      region: "cn-hz",
    },
    joinRoom: {
      uid: "用户 uid",
      uuid: "房间 UUID",
      roomToken: "房间 Token",
    },
    managerConfig: {
      cursor: true,
    },
  });
  window.app = app;
  return mount(app, div);
}
 
mountFastboard(document.getElementById("app"));

运行项目

在项目根目录下运行下列命令安装依赖：
Shell
```
npm install
```
运行项目：
Shell
```
npm run dev
```

你的浏览器会自动打开以下页面：

你可以选择右侧工具栏上的铅笔、文字或形状工具，在白板上写写画画；可以点击工具栏最下方的图标，体验丰富的插件功能；当前页面写满时，可以点击右下方的图标，新增页面，并使用箭头切换页面。

注意

在本地服务器（localhost）运行 Web 应用仅作为测试用途。部署生产环境时，请确保使用 HTTPS 协议。

后续步骤

体验完带 UI 的白板功能后，你可以调用 Fastboard SDK 的 API 并自定义 UI，以实现插入图片、播放音视频、演示文档等功能。详见展示文件。

技术原理​

前提条件​

服务端实现​

1. 创建房间​

2. 生成 Room Token​

客户端实现​

1. 添加依赖项​

2. 实现用户界面​

3. 实现加入房间​

运行项目​

后续步骤​