使用 Fastboard 快速接入白板互动系统

有用户在体验了「Agora Flat 开源教室」之后反馈体验还不错，尤其是其中白板互动、PPT展示那一部分用起来很简单、也很方便。就过来问我们如何快速的将这一套白板互动、PPT展示系统引入到自己的产品里面。

flat 小班课

Agora Flat 是我们去年发布的一个开源在线互动教室，感兴趣的朋友可以点击链接来体验。

本篇文章就来做一个接入演示，以 Web 端为例带大家快速接入 Fastboard，拥有一套白板互动系统。移动端接入 Fastboard 教程请移步文章末尾查看对应链接。

首先我们要知道每一个可以操作的白板都有一个房间的概念，在进入这个白板房间之前我们需要获取到这个房间的门牌号（Room uuid）和钥匙（Room Token）。

第一步、获取白板 Room uuid 和 Room Token

首先我们要有一个声网开发者账号，可以前往 console.agora.io 注册。登录成功后创建一个项目，在项目配置里面开通互动白板服务，如下图。

开通互动白板服务后，我们可以获取到白板配置信息，里面包括 AppId 和 SDK Token。

接下来我们就可以拿 AppId 和 SDK Token 来调用白板服务器创建房间。

执行如下代码，调用白板服务的 API 来创建房间：

var url = "https://api.netless.link/v5/rooms";
var requestInit = {
  method: "POST",
  headers: {
    "content-type": "application/json",
    region: "cn-hz", // 指定处理该请求的白板数据中心，此处选的是杭州
    token: "NETLESSSDK_YWs9ZzdkR.......", // 签发的 SDK Token，需提前准备
  },
};

window
  .fetch(url, requestInit)
  .then(function (response) {
    return response.json();
  })
  .then(function (roomJSON) {
    // 创建房间成功，获取描述房间信息的 roomJSON
    console.log(roomJSON);
  })
  .catch(function (err) {
    // 失败了，打印出 Error 以便分析为何失败
    console.error(err);
  });

如果执行成功，将创建一个实时互动房间。白板服务端会返回一个 JSON 形式的 object，来描述刚刚创建好的房间的信息。如下：

1440×701 92 KB

其中 uuid 就是我们需要的门牌号 Room uuid。

注意：建议在业务服务器上执行创建房间的操作，不要在前端或客户端上做。本章为了演示完整流程，用了前端的 window.fetch 方法调用白板服务端 API。请勿在正式 Web 应用中效仿此行为。

接下来要通过执行如下代码，调用白板服务端 API，为刚刚创建的房间签出 Room Token。

var url = "https://api.netless.link/v5/rooms";
var requestInit = {
  method: "POST",
  headers: {
    "content-type": "application/json",
    region: "cn-hz", // 指定处理该请求的白板数据中心，此处选的是杭州
    token: "NETLESSSDK_YWs9ZzdkR.......", // 签发的 SDK Token，需提前准备
  },
};

window
  .fetch(url, requestInit)
  .then(function (response) {
    return response.json();
  })
  .then(function (roomJSON) {
    // 创建房间成功，获取描述房间信息的 roomJSON
    console.log(roomJSON);
  })
  .catch(function (err) {
    // 失败了，打印出 Error 以便分析为何失败
    console.error(err);
  });

如果执行成功，将返回该房间的 Room Token。如下：

这个就是我们需要的房间钥匙 Room Token。

注意：由于必须通过白板服务端 API 签出 Room Token，而该行为必须用到 SDK Token。显然，出于安全方面的顾虑，该操作也不能在前端做。当前端需要 Room Token 时，应该先调用业务服务器的 API，再由业务服务器调用白板服务端 API 签出 Room Token。

第二步、客户端实现白板互动系统

添加依赖项

创建一个名为 fastboard_quickstart 的文件夹，通过命令行进入 fastboard_quickstart 目录并运行 npm init 命令来创建 package.json 文件。

然后命令行里执行下面的命令来添加 Fastboard 的依赖。

npm add @netless/fastboard @netless/window-manager white-web-sdk

因为后面需要打包项目才可以运行，所以我们需要指定构建工具。本文推荐使用 Vite。

我们手动在 package.json 文件下 devDependencies 中添加 vite 字段，并在 scripts 中定义项目运行的命令行。示例如下：

{
  "name": "fastboard_quickstart",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "vite build",
    "dev": "vite --open",
    "test": "echo "Error: no test specified" && exit 1"
  },
  "author": "",
  "license": "",
  "dependencies": {
    "@netless/fastboard": "^0.2.6",
    "@netless/window-manager": "^0.4.7",
    "white-web-sdk": "^2.16.10"
  },
  "devDependencies": {
    "vite": "latest"
  }
}

实现用户界面

在 fastboard_quickstart 文件夹中新建 index.html，将以下代码复制到 index.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>

这段代码中最主要的是要给挂载白板的元素一个宽高，要不然我们会看不到白板效果。

实现加入房间逻辑

在 fastboard_quickstart 文件夹中新建 main.js，将以下代码复制到 main.js 实现加入白板房间的逻辑：

import { createFastboard, mount } from "@netless/fastboard";

let app;
async function mountFastboard(div) {
  app = await createFastboard({
    sdkConfig: {
      appIdentifier: "上文获取到的 AppId",
      region: "cn-hz", // 指定处理该请求的白板数据中心，此处选的是杭州
    },
    joinRoom: {
      uid: "用户 uid", //每个用户的唯一 ID
      uuid: "上文获取到的 room uuid",
      roomToken: "上文获取到的 Room Token",
    },
    managerConfig: {
      cursor: true, //开启用户光标
    },
  });
  window.app = app;
  return mount(app, div);
}

mountFastboard(document.getElementById("app"));