# 加入白板房间 (/zh-CN/realtime-media/whiteboard/fastboard-sdk/get-started/join-room-fb/web)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
声网互动白板房间提供丰富的编辑工具,支持展示静态图片、动态 PPT、H5 课件等多种格式的文件,不同终端用户能在白板上实时展示想法,轻松实现多人互动协作。
本文介绍如何建立一个简单的项目,使用声网互动白板 SDK 加入房间并实现基础的白板功能。
:::warning[注意]
由于浏览器的安全策略对除 127.0.0.1 以外的 HTTP 地址作了限制,声网互动白板 SDK 仅支持 HTTPS 协议以及 `http://localhost`(`http://127.0.0.1`),请勿使用 HTTP 协议部署你的项目。
:::
## 技术原理 [#技术原理-2]
下图展示了加入声网互动白板房间的基本流程。
当你的 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 以加入互动白板房间。
## 前提条件 [#前提条件-2]
- 满足[最低版本要求的浏览器](/zh-CN/realtime-media/whiteboard#如何选择白板-sdk-和-fastboard-sdk)。
- 有效的声网[开发者账号](/zh-CN/introduction/quickstart)。
- 已在声网控制台[开启互动白板服务](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service)并获取[白板项目的 AppIdentifier 和 SDK Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。
- [Node.js 及 npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)。
## 服务端实现 [#服务端实现-2]
在 App 客户端加入互动白板房间前,你需要在 App 服务端调用声网互动白板提供的 RESTful API 创建房间、获取房间 UUID 并生成 Room Token,并将房间 UUID 和 Room Token 传给 App 客户端。
:::warning[注意]
你需要自行实现将房间 UUID 和 Room Token 下发给 App 客户端的逻辑。
:::
### 1. 创建房间 [#1-创建房间-2]
调用互动白板服务端 RESTful API 创建一个房间。详见[创建房间(POST)](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room)。
**请求示例**
你可以使用以下 Node.js 脚本发送请求:
:::info[信息]
使用 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 [#2-生成-room-token-2]
创建房间并获取新建房间的 `uuid` 后,你需要在 App 服务端生成 Room Token 并下发给 App 客户端。当 App 客户端加入房间时,声网互动白板服务端会使用该 Token 对其鉴权。
你可以通过以下方式在 App 服务端生成 Room Token:
- 使用代码生成 Room Token,详见[在 App 服务端生成 Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/generate-token#在-app-服务端生成-token)。(推荐)
- 调用互动白板服务端 RESTful API 生成 Room Token,详见[生成 Room Token(POST)](/zh-CN/api-reference/api-ref/whiteboard/restful/generate-room-token)。
下面以调用 RESTful API 的方式为例介绍如何生成 Room Token。
**请求示例**
你可以使用以下 Node.js 脚本发送请求:
:::info[信息]
使用 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
```
## 客户端实现 [#客户端实现-2]
创建一个名为 `fastboard_quickstart` 的文件夹。一个 Web 客户端项目至少需包含以下文件:
- `package.json`: 安装并管理项目依赖。
- `index.html`: 用于设计 Web 应用的用户界面。
- `main.js`: 实现具体应用逻辑的代码。
### 1. 添加依赖项 [#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](https://vitejs.dev/)。在 `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. 实现用户界面 [#2-实现用户界面-1]
将以下代码复制到 `index.html` 实现应用的用户界面:
```html
Vite App
```
:::warning[注意]
请确保给挂载白板的元素设置宽和高,否则无法看到白板页面。
:::
### 3. 实现加入房间 [#3-实现加入房间-2]
调用 Fastboard SDK 的如下方法加入白板房间:
1. 调用 `createFastboard` 创建一个 `FastboardApp` 实例并加入白板房间。
2. 调用 `createUI` 将 `FastboardApp` 实例挂载到网页元素中。
调用 `createFastboard` 方法时,你需要填入以下参数:
- 在 `sdkConfig` 中传入 SDK 配置参数:
- `appIdentifier`: 互动白板项目的 AppIdentifier。详见[获取 AppIdentifier](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。
- `region`:数据中心,必须和创建房间时设置的数据中心一致。
- 在 `joinRoom` 中传入房间配置参数:
- `uid`: 用户的唯一标识符,字符串格式,长度不能超过 1024 字节。
- `uuid`: 房间 UUID,即房间的唯一标识符。详见[创建房间](#createroom)。
- `roomToken`: 用于鉴权的 Room Token。生成该 Room Token 使用的房间 UUID 必须和上面的房间 UUID 一致。详见[生成 Room Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/generate-token#在-app-服务端生成-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"));
```
## 运行项目 [#运行项目-2]
1. 在项目根目录下运行下列命令安装依赖:
```shell
npm install
```
2. 运行项目:
```shell
npm run dev
```
你的浏览器会自动打开以下页面:

你可以选择右侧工具栏上的铅笔、文字或形状工具,在白板上写写画画;可以点击工具栏最下方的图标,体验丰富的插件功能;当前页面写满时,可以点击右下方的图标,新增页面,并使用箭头切换页面。
:::warning[注意]
在本地服务器(localhost)运行 Web 应用仅作为测试用途。部署生产环境时,请确保使用 HTTPS 协议。
:::
## 后续步骤 [#后续步骤-2]
体验完带 UI 的白板功能后,你可以调用 Fastboard SDK 的 API 并自定义 UI,以实现插入图片、播放音视频、演示文档等功能。详见[展示文件](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/manage-whiteboard/present-files-fb)。
## 推荐教具插件配置 [#推荐教具插件配置-2]
推荐传入 `enableAppliancePlugin` 配置对象;运行示例前按[教具插件介绍与启用](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/overview)准备对应版本的 Full/Sub Worker 资源,并引入插件 CSS。