加入白板房间

  • Web

更新时间

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

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

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

注意

由于浏览器的安全策略对除 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 以加入互动白板房间。

前提条件

服务端实现

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

注意

你需要自行实现将房间 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:

下面以调用 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 文件并添加必要的依赖项:

  1. 进入 fastboard_quickstart 目录并运行 npm init 命令来创建 package.json 文件。

  2. 运行如下命令安装最新版本的 Fastboard SDK 及相关依赖项:

    Shell
    npm add @netless/fastboard@1.1.10 @netless/window-manager@1.0.25 white-web-sdk@2.16.59 @netless/appliance-plugin@1.1.45

    各字段的含义如下:

    • @netless/fastboard:Fastboard SDK。
    • @netless/window-manager:窗口管理插件,用于实现和管理多窗口应用。
    • white-web-sdk:提供互动白板核心功能的 SDK。
  3. 为运行和打包项目,你需要指定构建工具。本文使用 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 的如下方法加入白板房间:

  1. 调用 createFastboard 创建一个 FastboardApp 实例并加入白板房间。
  2. 调用 createUI 将 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, createUI } 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",
    },
    enableAppliancePlugin: {
      cdn: {
        fullWorkerUrl: "/appliance-1.1.45/fullWorker.js",
        subWorkerUrl: "/appliance-1.1.45/subWorker.js",
      },
    },
    managerConfig: {
      cursor: true,
    },
  });
  window.app = app;
  return createUI(app, div);
}
 
mountFastboard(document.getElementById("app"));

运行项目

  1. 在项目根目录下运行下列命令安装依赖:

    Shell
    npm install
  2. 运行项目:

    Shell
    npm run dev

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

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

注意

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

后续步骤

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

推荐教具插件配置

推荐传入 enableAppliancePlugin 配置对象;运行示例前按教具插件介绍与启用准备对应版本的 Full/Sub Worker 资源,并引入插件 CSS。