本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护





All

Console 官网 Community Technical support





Join a Whiteboard Room

Last updated 2022/04/15 01:50:39

Agora Interactive Whiteboard rooms enable users to present ideas, share multi-media content, and collaborate on projects on a shared whiteboard from multiple devices simultaneously.

This article shows you the minimal code to join an interactive whiteboard room and implement basic whiteboard features.

Understand the tech

The following figure shows the workflow to join an Agora Interactive Whiteboard room.

When an app client requests to join an interactive whiteboard room, the app client and your app server interact with the Agora Interactive Whiteboard server in the following steps：

The app server sends a request with the SDK token to the Agora Interactive Whiteboard server to create a whiteboard room.
The Agora Interactive Whiteboard server returns the room UUID to the app server when a room is created successfully.
The app server generates a room token using the returned room UUID and sends the room token and UUID to the app client.
The app client initializes a whiteboard SDK instance with the App Identifier got from the Agora Console.
The app client calls a method to join the interactive whiteboard room using the room UUID and room token.

Prerequsites

Before proceeding, you must have the following:

A web browser that meets the minimum version requirements.
A valid Agora account.
An Agora project with the whiteboard service enabled. Get the app identifier and SDK token from the Agora Console. See Enable and Configure Interactive Whiteboard Service.

Create a basic Web application

Follow the steps to create a minimal Web application that has the following structure:

agora_join_whiteboard_room/
├── index.html
└── joinWhiteboard.js

Create a new folder called agora_join_whiteboard_room.
In agora_join_whiteboard_room, create the following files:
- index.html: The visual user interface.
- joinWhiteboard.js: The programmable interface that uses WhiteWebSdk to implement the app logic.

In index.html, add the following code to include the app logic in the UI:

<!DOCTYPE html>
<html>
 <head>
     <script src="./joinWhiteboard.js"></script>
 </head>
 <body>
     <div id="whiteboard" style="width: 100%; height: 100vh;"></div>
 </body>
</html>

After setting up the basic structure, you can now build the whiteboard functionality into the applcation.

Create a whiteboard room from your app server

Before an app client requests to join a room, you need to call /v5/rooms (POST) on your app server to create a room.

You can use the following Node.js script as a request example:

var request = require("request");
var options = {
  "method": "POST",
  "url": "https://api.netless.link/v5/rooms",
  "headers": {
  "token": "Your SDK Token",
  "Content-Type": "application/json",
  "region": "us-sv"
  },
  body: JSON.stringify({
    "isRecord": false
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

If the request is successful, Agora's server for the whiteboard service returns information about the created room, including the uuid, which is the unique identifier of the room. You need to pass in this parameter when an app client joins the room.

The followings is a response example:

{
    "uuid": "4a50xxxxxx796b", // The room UUID
    "teamUUID": "RMmLxxxxxx15aw",
    "appUUID": "i54xxxxxx1AQ",
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

Generate a room token

After creating a room and getting the uuid of the room, your app server needs to generate a room token and send it to the app client. When an app client joins a room, Agora's server uses the room token for authentication.

To generate a room token on your app server, you can:

Use code. See Generate a Token from your app server. (Recommended)
Call the Interactive Whiteboard RESTful API. See Generate a Room Token (POST).

You can use the following Node.js script as a request example:

var request = require('request');
var options = {
  "method": "POST",
   // Replace <Room UUID> with the uuid of your room
  "url": "https://api.netless.link/v5/tokens/rooms/<Room UUID>", 
  "headers": {
  "token": "Your SDK Token",
  "Content-Type": "application/json",
  "region": "us-sv"
  },
  body: JSON.stringify({"lifespan":3600000,"role":"admin"})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

If the request is successful, Agora's server returns a room token. The following is a response example:

"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token

Join the whiteboard room from your app client

This section shows how to integrate the whiteboard SDK into your application and call the methods provided by the SDK to join the existing Interactive Whiteboard room.

Import the Agora Interactive Whiteboard SDK.
In index.html, add <script src="https://sdk.netless.link/white-web-sdk/2.15.16.js"></script> right below the <head> line to import the whiteboard SDK.

<!DOCTYPE html>
 <html lang="en">
 <head>
      <script src="https://sdk.netless.link/white-web-sdk/2.15.16.js"></script>
      <script src="./joinWhiteboard.js"></script>
 </head>
 <body>
      <div id="whiteboard" style="width: 100%; height: 100vh;"></div>
 </body>
 </html>

Create a WhiteWebSdk instance and join the room. You need to pass in the following parameters:

appIdentifier: The App Identifier of the whiteboard project in Agora Console. See Get security credentials for your whiteboard project.
region: The data center, which must be the same as the data center you chose when creating the room.

Open joinWhiteboard.js and add the following code:

var whiteWebSdk = new WhiteWebSdk({
  // Pass in your App Identifier.
  appIdentifier: "Your App Identifier",
  // Set the data center as Silicon Valley, US.
  region: "us-sv",
})

var joinRoomParams = {
  uuid: "Your room UUID",
  // The unique identifier of a user. If you use versions earlier than v2.15.0, do not add this line.
  uid: "user uid",
  roomToken: "Your room token",
};

// Join the whiteboard room and display the whiteboard on the web page.
whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {
    room.bindHtmlElement(document.getElementById("whiteboard"));
}).catch(function(err) {
    console.error(err);
});

Test your app

Open index.html in your browser. You should see a blank page. If the application runs successfully, you can use your mouse to write and draw on the page.

Reference

This section provides additonal infromation for your reference.

APIs used in this section

RESTful APIs:
- https://api.netless.link/v5/rooms (POST)
- https://api.netless.link/v5/tokens/rooms/{uuid} (POST)
APIs of WhiteWebSdk
- joinRoom

Iintegrate the whiteboard SDK through npm

In addition to getting the whiteboard SDK through CDN, you can integrate the SDK into your application through npm.

Navigate to your project folder and run the following command to install the SDK:
```
npm install white-web-sdk
```

Import the SDK in the index.js file:

var WhiteWebSdk = require("white-web-sdk");

Is this page helpful?

Yes