加入白板房间
- HarmonyOS
更新时间
了解如何快速接入互动白板 SDK,完成环境准备、参数配置、示例运行和核心流程验证。
声网互动白板房间提供丰富的编辑工具,支持展示静态图片、动态 PPT、H5 课件等多种格式的文件,不同终端用户能在白板上实时展示想法,轻松实现多人互动协作。本文介绍如何建立一个简单的项目,使用声网互动白板 SDK 加入房间并实现基础的白板功能。
技术原理
下图展示了加入声网互动白板房间的基本流程。
当你的 App 客户端请求加入互动白板房间时:
- 你的 App 服务端使用 SDK Token 向声网互动白板服务端发起创建房间的请求。
- 成功创建房间后,声网互动白板服务端向你的 App 服务端返回新建房间的房间 UUID。
- 你的 App 服务端使用房间 UUID 生成 room Token,并将房间 UUID 和 room Token 发送给 App 客户端。
- App 客户端使用从声网控制台获取的 AppIdentifier 初始化互动白板 SDK 实例。
- App 客户端调用 SDK 的方法并传入房间 UUID 和 room Token 以加入互动白板房间。
前提条件
- Android Studio
- Android SDK API level 21+
- 有效的声网开发者账号。
- 已在声网控制台开启互动白板服务并获取白板项目的 AppIdentifier 和 SDK Token。
创建 Android 项目
使用 Android Studio 创建一个 Android 项目。
- 项目名设为
WhiteBoard。 - Package 名设为
com.example.whiteboard。 - Activity 类型选择 Empty Activity。
- Minimum SDK 选择 API 21。
添加权限
在 AndroidManifest.xml 文件中添加访问网络权限:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.whiteboard">
<uses-permission android:name="android.permission.INTERNET" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/Theme.WhiteBoard">
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>获取 SDK
打开根目录下的 build.gradle 进行以下配置:
allprojects {
repositories {
google()
mavenCentral()
// 添加以下内容
maven { url 'https://jitpack.io' }
// 对于国内用户,如果 Gradle sync 失败,可以选择国内镜像,例如阿里云 Maven 镜像
maven { url 'https://maven.aliyun.com/nexus/content/repositories/releases/'}
}
}然后打开 app 目录下的 build.gradle 进行如下配置:
dependencies {
// 当前正式版
implementation 'com.github.netless-io:whiteboard-android:2.16.134'
}关于声网互动白板 SDK 的最新版本,详见发版说明。
防止代码混淆
在 proguard-rules.pro 文件中添加以下语句,防止代码混淆:
# SDK model
-keep class com.herewhite.** { *; }实现步骤
现在,我们已经将声网互动白板 SDK 集成到项目中了。接下来我们要调用声网互动白板 SDK 提供的核心 API 实现基础的白板功能。
1. 创建房间
在 App 客户端加入互动白板房间前,你需要在 App 服务端调用互动白板服务端 RESTful API 创建一个房间。详见创建房间(POST)。
请求示例
你可以使用以下 Node.js 脚本发送请求:
信息
使用 Node.js 发送 HTTP 请求前安装 request 模块。你可以运行 npm install request 安装。
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 客户端加入房间时需要传入该参数。
响应示例
{
"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 安装。
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。
响应示例
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token3. 创建 UI
修改 activity_main.xml 为如下内容,可以看到整个视图由一个白板页面填充,页面 com.herewhite.sdk.WhiteboardView 由互动白板 SDK 实现。
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/activity_main"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
tools:context=".MainActivity">
<com.herewhite.sdk.WhiteboardView
android:id="@+id/white"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:visibility="visible" />
</LinearLayout>4. 初始化 SDK 并加入房间
编辑 MainActivity.java,实现从初始化 SDK 到加入房间的基本操作。你需要传入以下参数:
appId:互动白板项目的 AppIdentifier。详见获取 AppIdentifier。uuid:房间的 UUID。详见创建房间。uid:用户的唯一标识符,字符串格式,长度不能超过 1024 字节。如果你使用 2.15.0 或之后版本的 SDK,必须传入该参数;如果你使用 2.15.0 之前版本的 SDK,则不需要传入该参数。roomToken:用于鉴权的 Room Token。生成该 Room Token 使用的房间 UUID 必须和上面的房间 UUID 一致。详见生成 Room Token。region:数据中心,必须和创建房间时设置的数据中心一致。
package com.example.whiteboard;
import android.os.Bundle;
import android.util.Log;
import androidx.appcompat.app.AppCompatActivity;
import com.herewhite.sdk.Room;
import com.herewhite.sdk.RoomListener;
import com.herewhite.sdk.RoomParams;
import com.herewhite.sdk.WhiteSdk;
import com.herewhite.sdk.WhiteSdkConfiguration;
import com.herewhite.sdk.WhiteboardView;
import com.herewhite.sdk.domain.MemberState;
import com.herewhite.sdk.domain.Promise;
import com.herewhite.sdk.domain.Region;
import com.herewhite.sdk.domain.RoomPhase;
import com.herewhite.sdk.domain.RoomState;
import com.herewhite.sdk.domain.SDKError;
import com.herewhite.sdk.domain.WindowParams;
public class MainActivity extends AppCompatActivity {
private WhiteboardView whiteboardView;
private WhiteSdk whiteSdk;
private Room room;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
whiteboardView = findViewById(R.id.white);
WhiteSdkConfiguration config = new WhiteSdkConfiguration("APP_IDENTIFIER", true);
config.setRegion(Region.cn);
// 同一房间各端一致使用高性能绘制插件。
config.setUseMultiViews(true);
config.setEnableAppliancePlugin(true);
whiteSdk = new WhiteSdk(whiteboardView, this, config);
RoomParams params = new RoomParams("ROOM_UUID", "ROOM_TOKEN", "CLIENT_UID");
params.setRegion(Region.cn);
params.setWritable(true);
params.setWindowParams(new WindowParams());
RoomListener listener = new RoomListener() {
@Override public void onPhaseChanged(RoomPhase phase) { }
@Override public void onDisconnectWithError(Exception error) { }
@Override public void onKickedWithReason(String reason) { }
@Override public void onRoomStateChanged(RoomState modifyState) { }
@Override public void onCanUndoStepsUpdate(long canUndoSteps) { }
@Override public void onCanRedoStepsUpdate(long canRedoSteps) { }
@Override public void onCatchErrorWhenAppendFrame(long userId, Exception error) { }
};
whiteSdk.joinRoom(params, listener, new Promise<Room>() {
@Override public void then(Room joinedRoom) {
room = joinedRoom;
MemberState state = new MemberState();
state.setCurrentApplianceName("pencil");
state.setStrokeColor(new int[]{255, 0, 0});
room.setMemberState(state);
}
@Override public void catchEx(SDKError error) {
Log.e("Whiteboard", error.getMessage());
}
});
}
private boolean leaving;
@Override
public void onBackPressed() {
if (leaving) return;
if (whiteSdk == null) { finish(); return; }
leaving = true;
whiteSdk.leaveRoom(new Promise<Object>() {
@Override public void then(Object completion) {
// 仅通知退房完成;不是房间状态快照。
room = null;
whiteSdk.releaseRoom();
finish(); // onDestroy 再销毁 View。
}
@Override public void catchEx(SDKError error) {
leaving = false;
Log.e("Whiteboard", "退出失败,请重试", error);
}
});
}
@Override
protected void onDestroy() {
// 正常退出已在 onBackPressed 等待;系统强制销毁不提供异步等待窗口。
if (whiteboardView != null) whiteboardView.destroy();
super.onDestroy();
}
}5. 接入多窗口
SDK 已通过内嵌 Bridge 集成 Window Manager。创建 WhiteSdk 前启用多 View,入房前将窗口配置传给 RoomParams;步骤 4 的完整示例已包含这些配置:
import com.herewhite.sdk.domain.WindowParams;
// 创建 WhiteSdk 前设置。
config.setUseMultiViews(true);
// joinRoom 前设置;WindowParams 可进一步配置窗口显示。
params.setWindowParams(new WindowParams());入房成功后,SDK 自动在 WhiteboardView 内挂载窗口管理器。窗口配置和课件控制见统一页面控制。
6. 接入动态 PPT
内嵌 Bridge 已注册 app-slide。业务服务端完成动态 PPT 转换后,在入房成功回调中,或其后的业务按钮中,用 WindowAppParam.createSlideApp 创建参数,再调用 room.addApp:
import com.herewhite.sdk.domain.WindowAppParam;
import com.herewhite.sdk.domain.Promise;
import com.herewhite.sdk.domain.SDKError;
WindowAppParam slide = WindowAppParam.createSlideApp(
"CONVERSION_TASK_UUID",
"https://convertcdn.netless.link/dynamicConvert",
"教学课件.pptx"
);
room.addApp(slide, new Promise<String>() {
@Override public void then(String appId) {
android.util.Log.i("Whiteboard", "动态 PPT 窗口 ID:" + appId);
}
@Override public void catchEx(SDKError error) {
android.util.Log.e("Whiteboard", error.getMessage());
}
});第一个参数是转换任务 UUID,第二个参数是转换结果的资源地址前缀,末尾不带 /,不能填写 PPT 源文件地址。此工厂方法为窗口生成独立场景目录。创建 App 需要可写权限;房间中已存在的课件会同步显示,不要在每次入房时重复插入。返回窗口 ID 不表示课件资源和首帧全部加载完成。更多说明见展示文件。
7. 开启新教具
创建 WhiteSdk 前同时开启多 View 与新教具;步骤 4 的示例已开启:
config.setUseMultiViews(true);
config.setEnableAppliancePlugin(true);SDK 已内嵌 Appliance Plugin 与 Worker 资源,业务继续使用 room.setMemberState 等原生 API 切换 Pencil、Selector、Eraser、Shape、Text 等教具,无需额外安装或注册 Web 插件。同一房间各端应一致启用。
入房前可通过 RoomParams.appliancePluginOptions 设置教具插件参数。自定义教具、背景图和 Auto Shape 接入见教具插件介绍与启用。
WhiteSdkConfiguration 的初始化开关需在 SDK 创建前设置,入房后不能通过修改此对象启用新教具。SDK 初始化错误通过 CommonCallback.sdkSetupFail 处理。
编译并运行项目
在 Android Studio 中编译并在模拟器或真机上运行项目。入房成功后可在白板上书写,业务按钮可通过步骤 6 的原生 API 打开动态 PPT。
配置远端参数
需要在入房前读取远端参数时,参见动态配置。地址在创建 SDK 前设置,本地显式参数优先;读取失败回退本地参数。
声网互动白板房间提供丰富的编辑工具,支持展示静态图片、动态 PPT、H5 课件等多种格式的文件,不同终端用户能在白板上实时展示想法,轻松实现多人互动协作。
本文介绍如何建立一个简单的项目,使用声网互动白板 SDK 加入房间并实现基础的白板功能。
技术原理
下图展示了加入声网互动白板房间的基本流程。
当你的 App 客户端请求加入互动白板房间时:
- 你的 App 服务端使用 SDK Token 向声网互动白板服务端发起创建房间的请求。
- 成功创建房间后,声网互动白板服务端向你的 App 服务端返回新建房间的房间 UUID。
- 你的 App 服务端使用房间 UUID 生成 room Token,并将房间 UUID 和 room Token 发送给 App 客户端。
- App 客户端使用从声网控制台获取的 AppIdentifier 初始化互动白板 SDK 实例。
- App 客户端调用 SDK 的方法并传入房间 UUID 和 room Token 以加入互动白板房间。
前提条件
- Xcode 10.10+
- CocoaPods 接入:iOS 10.0+;SwiftPM 接入:iOS 12.0+
- CocoaPods 最新版本。
- 有效的声网开发者账号。
- 已在声网控制台开启互动白板服务并获取白板项目的 AppIdentifier 和 SDK Token。
创建项目
参考以下步骤在 Xcode 中创建一个 Single View App。
创建一个 Objective-C 项目,项目设置如下:
- Product Name 设为
Whiteboard。 - Organization Identifier 设为
agora。 - Language 选择
Objective-C。
创建一个 Swift 项目,项目设置如下:
- Product Name 设为
Whiteboard。 - Organization Identifier 设为
agora。 - Language 选择
Swift。 - User Interface 选择
Storyboard。
声网互动白板 SDK 使用 Objective-C 语言开发。要在 Swift 项目中使用 Objective-C 代码,你还需要在项目中创建一个 Objective-C 桥接文件,步骤如下:
- 在项目中添加
Whiteboard-Bridging_Header.h文件。 - 在
Whiteboard-Bridging_Header.h文件中添加如下行引用Whiteboard.h:
#import <Whiteboard/Whiteboard.h>获取 SDK
-
在 Terminal 里进入项目所在路径。运行以下命令创建
Podfile文件。项目路径下会出现一个Podfile文本文件。Shell pod init -
在生成的
Podfile文件中添加如下内容:Ruby platform :ios, '10.0' target 'Whiteboard' do pod 'Whiteboard', '2.16.147' end -
运行以下命令安装 SDK:
Shell pod install安装完成后,你可以点击打开项目的
Whiteboard.xcworkspace文件,对项目进行后续编辑。
信息
对于中国大陆用户,如果在执行 pod install 命令时由于网络原因失败,可以使用 TUNA 镜像源。
实现步骤
现在,我们已经将声网互动白板 SDK 集成到项目中了。接下来我们要调用声网互动白板 SDK 提供的核心 API 实现基础的白板功能。
1. 创建房间
在 App 客户端加入互动白板房间前,你需要在 App 服务端调用互动白板服务端 RESTful API 创建一个房间。详见创建房间(POST)。
请求示例
你可以使用以下 Node.js 脚本发送请求:
信息
使用 Node.js 发送 HTTP 请求前安装 request 模块。你可以运行 npm install request 安装。
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 客户端加入房间时需要传入该参数。
响应示例
{
"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 安装。
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。
响应示例
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token3. 创建白板视图
创建 WhiteBoardView 并添加到页面,设置合适的显示尺寸。以下完整示例的 setupViews 方法负责这一步。
4. 初始化 SDK 并加入房间
编辑 ViewController.m,实现从添加 View、初始化 SDK 到加入房间的基本操作。你需要传入以下参数:
appIdentifier:互动白板项目的唯一标识符。详见获取 AppIdentifier。uuid:房间的唯一标识符。详见创建房间。uid:用户的唯一标识符,字符串格式,长度不能超过 1024 字节。如果你使用 2.15.0 或之后版本的 SDK,必须传入该参数;如果你使用 2.15.0 之前版本的 SDK,则不需要传入该参数。roomToken:用于鉴权的 Room Token。生成该 Room Token 使用的房间 UUID 必须和上面的房间 UUID 一致。详见生成 Room Token。region:数据中心,必须和创建房间时设置的数据中心一致。
// ViewController.m
// WhiteBoard
#import "ViewController.h"
#import <Whiteboard/Whiteboard.h>
@interface ViewController ()
@property(nonatomic, strong) WKWebViewConfiguration *config;
@property(nonatomic, strong) WhiteBoardView *boardView;
@property(nonatomic, strong) WhiteSDK *sdk;
@property(nonatomic, strong) WhiteRoom *room;
@property(nonatomic, strong) WhiteMemberState *memberState;
@property(nonatomic, strong) WhiteRoomConfig *roomConfig;
@property(nonatomic, strong) WhiteSdkConfiguration *sdkConfig;
@property(nonatomic, weak, nullable) id<WhiteCommonCallbackDelegate> commonDelegate;
@property(nonatomic, weak, nullable) id<WhiteRoomCallbackDelegate> roomCallbackDelegate;
@end
@implementation ViewController
// 添加 View
- (void)setupViews
{
self.config = [[WKWebViewConfiguration alloc] init];
// // 在此项目中将白板 View 设为全屏
self.boardView = [[WhiteBoardView alloc] initWithFrame:(CGRectMake(0.0f, 0.0f, self.view.bounds.size.width, self.view.bounds.size.height)) configuration:(self.config)];
[self.view addSubview:(self.boardView)];
}
// 初始化 SDK
- (void)initSDK
{ // 传入互动白板项目的 AppIdentifier
self.sdkConfig = [[WhiteSdkConfiguration alloc] initWithApp:@"Your AppIdentifier"];
// 设置数据中心为中国杭州
self.sdkConfig.region = WhiteRegionCN;
self.sdkConfig.useMultiViews = YES;
self.sdkConfig.enableAppliancePlugin = YES;
// 初始化 SDK
self.sdk = [[WhiteSDK alloc] initWithWhiteBoardView:self.boardView config:self.sdkConfig commonCallbackDelegate:self.commonDelegate];
}
// 加入房间
- (void)joinRoom
{ // 设置房间 UUID,用户 uid 和 Room Token。如果你使用 2.15.0 之前版本的 SDK,不需要传入 uid:@"用户 uid"。
self.roomConfig = [[WhiteRoomConfig alloc] initWithUUID:@"Your UUID" roomToken:@"Your room token" uid:@"用户 uid"];
self.roomConfig.region = WhiteRegionCN;
self.roomConfig.isWritable = YES;
self.roomConfig.windowParams = [WhiteWindowParams new];
// 设置白板工具
self.memberState = [[WhiteMemberState alloc] init];
self.memberState.currentApplianceName = AppliancePencil;
self.memberState.strokeColor = @[ @255, @0, @0 ];
// 加入房间
[self.sdk joinRoomWithConfig:self.roomConfig
callbacks:self.roomCallbackDelegate
completionHandler:^(BOOL success, WhiteRoom *_Nonnull room, NSError *_Nonnull error) {
if (success)
{
self.room = room;
[self.room setMemberState:(self.memberState)];
NSLog(@"Successfully joined the room");
}
else
{
NSLog(@"Errors when joining room");
}
}];
}
// 在 viewDidLoad 方法中依次进行 View 添加,SDK 初始化,加入房间操作
- (void)viewDidLoad
{
[super viewDidLoad];
[self setupViews];
[self initSDK];
[self joinRoom];
}
@end// ViewController.swift
// Whiteboard
import UIKit
import WebKit
import Whiteboard
class ViewController: UIViewController {
var config: WKWebViewConfiguration?
var boardView: WhiteBoardView?
var roomConfig: WhiteRoomConfig?
var memberState: WhiteMemberState?
var room: WhiteRoom?
var sdk: WhiteSDK?
var sdkConfig: WhiteSdkConfiguration?
var commonDelegate: WhiteCommonCallbackDelegate?
var roomCallbackDelegate: WhiteRoomCallbackDelegate?
// 添加 View
func setupViews() {
self.config = WKWebViewConfiguration()
// 在此项目中将白板 View 设为全屏
self.boardView = WhiteBoardView(
frame: CGRect(x: 0, y: 0, width: self.view.bounds.width, height: self.view.bounds.height),
configuration: self.config!)
self.view.addSubview(self.boardView!)
}
// 初始化 SDK
func initSDK() { // 传入互动白板项目的 AppIdentifier
self.sdkConfig = WhiteSdkConfiguration(app: "APP_IDENTIFIER")
// 设置数据中心为中国杭州
sdkConfig?.region = WhiteRegionKey.CN
sdkConfig?.useMultiViews = true
sdkConfig?.enableAppliancePlugin = true
// 初始化 SDK
self.sdk = WhiteSDK(
whiteBoardView: self.boardView!, config: self.sdkConfig!,
commonCallbackDelegate: self.commonDelegate)
}
// 加入房间
func joinRoom() {
// 设置房间 UUID,用户 uid 和 Room Token。如果你使用 2.15.0 之前版本的 SDK,不需要传入 uid: "用户 uid"。
self.roomConfig = WhiteRoomConfig(
uuid: "Your uuid", roomToken: "Your room token", uid: "用户 uid")
self.roomConfig?.region = WhiteRegionKey.CN
self.roomConfig?.isWritable = true
self.roomConfig?.windowParams = WhiteWindowParams()
// 设置白板工具
self.memberState = WhiteMemberState()
self.memberState?.currentApplianceName = WhiteApplianceNameKey.AppliancePencil
self.memberState?.strokeColor = [255, 0, 0]
// 加入房间
self.sdk!.joinRoom(
with: self.roomConfig!, callbacks: roomCallbackDelegate,
completionHandler: { (Success, room, error) in
if Success {
self.room = room
self.room!.setMemberState(self.memberState!)
NSLog("Successfully joined the room")
} else {
NSLog("Errors when joining room")
}
})
}
// 在 viewDidLoad 方法中依次进行 View 添加,SDK 初始化,加入房间操作
override func viewDidLoad() {
super.viewDidLoad()
self.setupViews()
self.initSDK()
self.joinRoom()
}
}5. 接入多窗口
SDK 已通过内嵌 Bridge 集成 Window Manager。创建 WhiteSDK 前配置多 View,入房前配置 WhiteRoomConfig.windowParams。步骤 4 的完整示例已包含这些配置:
// 创建 WhiteSDK 前设置。
self.sdkConfig.useMultiViews = YES;
// joinRoomWithConfig 前设置。
self.roomConfig.windowParams = [WhiteWindowParams new];// 创建 WhiteSDK 前设置。
self.sdkConfig?.useMultiViews = true
// joinRoom 前设置。
self.roomConfig?.windowParams = WhiteWindowParams()入房后 SDK 在 WhiteBoardView 内挂载窗口管理器。配置和控制方法见新版 API 与多窗口课件控制。
6. 接入动态 PPT
内嵌 Bridge 已注册 app-slide。在入房成功后或业务“打开课件”按钮中,创建 WhiteAppParam 并调用 WhiteRoom.addApp:
WhiteAppParam *slide = [WhiteAppParam createSlideApp:@"/slides/lesson-1"
taskId:@"CONVERSION_TASK_UUID"
url:@"https://convertcdn.netless.link/dynamicConvert"
title:@"教学课件.pptx"];
[self.room addApp:slide completionHandler:^(NSString * _Nullable appId) {
if (appId.length > 0) {
NSLog(@"动态 PPT 窗口 ID:%@", appId);
} else {
NSLog(@"创建课件窗口未返回有效 ID");
}
}];let slide = WhiteAppParam.createSlideApp(
"/slides/lesson-1",
taskId: "CONVERSION_TASK_UUID",
url: "https://convertcdn.netless.link/dynamicConvert",
title: "教学课件.pptx"
)
self.room?.addApp(slide, completionHandler: { appId in
if let appId = appId, !appId.isEmpty {
print("动态 PPT 窗口 ID:\(appId)")
} else {
print("创建课件窗口未返回有效 ID")
}
})业务服务端先完成动态 PPT 转换。taskId 是转换任务 UUID,url 是资源地址前缀(末尾不带 /,不是 PPT 源文件地址)。第一个参数是以 / 开头的场景目录,每个 App 使用不同目录。创建 App 需要可写权限,房间内已有课件会同步显示,不要在每次入房时重复插入。返回 ID 不表示所有资源和首帧已加载。转换和展示方式见展示文件。
7. 开启新教具
创建 SDK 前同时启用多 View 与新教具。步骤 4 的完整示例已开启:
self.sdkConfig.useMultiViews = YES;
self.sdkConfig.enableAppliancePlugin = YES;self.sdkConfig?.useMultiViews = true
self.sdkConfig?.enableAppliancePlugin = trueAppliance Plugin 与 Worker 资源已随 SDK 内嵌,继续使用 WhiteRoom.setMemberState 等原生方法配置 Pencil、Selector、Eraser、Shape、Text 等教具。同房间各端应一致开启。入房前可通过 WhiteRoomConfig.appliancePluginOptions 传入插件参数,接入细节见教具插件介绍与启用。
这些开关必须在 SDK 初始化前设置;已经入房后修改配置对象不会开启插件。
编译并运行项目
在 Xcode 中编译并在模拟器或真机上运行项目。入房成功后可在白板书写,并使用步骤 6 的原生 API 打开动态 PPT。
等待退出完成
Whiteboard iOS 2.16.147 可用 leaveRoomWithCompletionHandler: 等待所属 Room 退出,完成回调的 NSError 为空表示成功。先处理退出结果,再销毁宿主或继续下一次入房。配置地址和参数优先级见动态配置。
声网互动白板房间提供丰富的编辑工具,支持展示静态图片、动态 PPT、H5 课件等多种格式的文件,不同终端用户能在白板上实时展示想法,轻松实现多人互动协作。
本文介绍如何创建 Web 项目、加入白板房间,并接入多窗口、动态 PPT 和新教具。示例采用 npm 与 Vite,使用 TypeScript 编写浏览器端模块。
注意
由于浏览器的安全策略对除 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 以加入互动白板房间。
前提条件
- 满足最低版本要求的浏览器。
- 有效的声网开发者账号。
- 已在声网控制台开启互动白板服务并获取白板项目的 AppIdentifier 和 SDK Token。
- Node.js 及 npm。
创建 Web 项目
在项目目录执行以下命令,初始化 npm 项目并安装开发服务器:
npm init -y
npm install -D vite
mkdir -p scripts创建以下目录结构;public 中的资源通过站点根路径访问:
.
├── index.html
├── scripts
│ └── index.ts
└── public将以下内容写入 index.html。容器必须有明确高度,浏览器模块在容器创建后加载:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>互动白板</title>
</head>
<body style="margin: 0;">
<div id="whiteboard" style="width: 100%; height: 100vh;"></div>
<script type="module" src="/scripts/index.ts"></script>
</body>
</html>获取 SDK
安装本页示例使用的 SDK、窗口管理器、动态 PPT App 和教具插件:
npm install white-web-sdk@2.16.59 @netless/window-manager@1.0.25 @netless/app-slide@0.2.108 @netless/appliance-plugin@1.1.45将步骤 3~7 的 TypeScript 代码依次放入同一个 scripts/index.ts。步骤 4~6 定义接入函数和注册 App,步骤 7 调用这些函数完成一次入房和插件初始化。
SDK 版本见发版说明。
实现步骤
先由业务服务端创建房间并生成 Room Token,再在浏览器端完成 SDK 初始化和接入。SDK Token 应保存在服务端,客户端只接收 Room Token。
1. 创建房间
在 App 客户端加入互动白板房间前,你需要在 App 服务端调用互动白板服务端 RESTful API 创建一个房间。详见创建房间(POST)。
请求示例
你可以使用以下 Node.js 脚本发送请求:
提示
使用 Node.js 发送 HTTP 请求前安装 request 模块。你可以运行 npm install request 安装。
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 客户端加入房间时需要传入该参数。
响应示例
{
"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 安装。
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。
响应示例
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token3. 创建 WhiteWebSdk 实例
填写项目的 appIdentifier 和房间所属数据中心。多窗口使用 useMobXState=true:
import { WhiteWebSdk, ApplianceNames, type InvisiblePluginClass, type Room } from 'white-web-sdk';
const whiteWebSdk = new WhiteWebSdk({
appIdentifier: 'APP_IDENTIFIER',
region: 'cn-hz',
useMobXState: true
});4. 加入房间
准备入房函数,传入步骤 1、2 获取的房间 UUID、Room Token,以及本用户唯一的 uid。region 必须与创建房间时一致。
useMultiViews=true 启用多 View;窗口管理器和教具插件需在入房前通过 invisiblePlugins 注册,实际列表在步骤 7 传入。disableMagixEventDispatchLimit=true 用于多窗口的事件分发。
async function joinWhiteboard(
invisiblePlugins: InvisiblePluginClass<string, any, any>[]
): Promise<Room> {
return await whiteWebSdk.joinRoom({
uuid: 'ROOM_UUID',
roomToken: 'ROOM_TOKEN',
uid: 'CLIENT_UID',
region: 'cn-hz',
isWritable: true,
useMultiViews: true,
disableMagixEventDispatchLimit: true,
invisiblePlugins
});
}5. 接入多窗口
WindowManager 管理主白板与课件窗口。入房成功后调用 WindowManager.mount,将界面挂载到页面容器,并引入窗口样式。本示例由 Window Manager 绑定视图,无需再调用 room.bindHtmlElement。
import { WindowManager } from '@netless/window-manager';
import '@netless/window-manager/dist/style.css';
async function mountWindows(room: Room, supportAppliancePlugin = false) {
const container = document.getElementById('whiteboard');
if (!container) throw new Error('找不到白板容器');
return await WindowManager.mount({
room,
container,
cursor: true,
supportAppliancePlugin
});
}同时接入步骤 7 的新教具时,传入 supportAppliancePlugin=true。窗口配置和页面控制见多窗口与课件控制。
6. 接入动态 PPT
安装的 @netless/app-slide 用于展示转换后的动态 PPT。在入房前调用 WindowManager.register 注册 Slide,这样新打开和房间中已存在的课件窗口都能加载 App 实现。
import AppSlide from '@netless/app-slide';
WindowManager.register({
kind: 'Slide',
src: AppSlide
});
async function openDynamicPpt(manager: WindowManager) {
const appId = await manager.addApp({
kind: 'Slide',
options: {
title: '教学课件.pptx',
scenePath: '/slides/lesson-1'
},
attributes: {
taskId: 'CONVERSION_TASK_UUID',
url: 'https://convertcdn.netless.link/dynamicConvert'
}
});
console.info('动态 PPT 窗口 ID:', appId);
return appId;
}业务服务端先完成动态 PPT 转换,taskId 使用转换任务 UUID,url 使用转换结果的资源地址前缀(不是 PPT 源文件地址,末尾不带 /)。scenePath 必须是以 / 开头的场景目录,同一房间内每个 App 使用不同目录。创建 App 需要可写权限;等待窗口挂载后再调用 addApp。注册实现是每个客户端的本地准备,addApp 创建的是房间内同步的实例,页面刷新或另一用户入房时不要重复插入同一课件。
addApp 返回 ID 不表示课件首帧和全部资源已加载。转换、展示与课件操作见展示文件。
7. 开启新教具
多窗口新教具通过 ApplianceMultiPlugin 接入。先准备同一插件版本的两份 Worker:
mkdir -p public/appliance-1.1.45
cp node_modules/@netless/appliance-plugin/dist/fullWorker.js public/appliance-1.1.45/
cp node_modules/@netless/appliance-plugin/dist/subWorker.js public/appliance-1.1.45/注册不可见插件并完成入房,挂载支持新教具的窗口管理器,然后调用 ApplianceMultiPlugin.getInstance 初始化。以下代码放在步骤 3~6 的代码之后:
import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
import '@netless/appliance-plugin/dist/style.css';
async function startWhiteboard() {
const room = await joinWhiteboard([
WindowManager as unknown as InvisiblePluginClass<string, any, any>,
ApplianceMultiPlugin
]);
const manager = await mountWindows(room, true);
const plugin = await ApplianceMultiPlugin.getInstance(manager, {
options: {
cdn: {
fullWorkerUrl: '/appliance-1.1.45/fullWorker.js',
subWorkerUrl: '/appliance-1.1.45/subWorker.js'
},
extras: { useBackgroundThread: true }
}
});
// 入房并完成插件初始化后设置初始教具。
room.setMemberState({ currentApplianceName: ApplianceNames.pencil });
// 在业务“打开课件”按钮中调用 openDynamicPpt(manager)。
// 返回实例供业务保存,避免刷新或重新入房时重复 addApp。
return { room, manager, plugin };
}
startWhiteboard().then(({ room, manager, plugin }) => {
// 保存实例并绑定业务按钮,例如按钮点击时调用 openDynamicPpt(manager)。
console.info('白板与新教具已初始化', room, manager, plugin);
}).catch(console.error);Web 通过上述注册、supportAppliancePlugin 和实例初始化启用新教具。插件提供 Pencil、Selector、Eraser、Shape、Text 等绘制与编辑能力,业务应用提供教具切换按钮。同一房间各端应一致启用新教具。
Worker 与主线程插件必须来自同一版本,站点需允许 Worker 加载。离开页面时先解除业务事件监听,等待 plugin.destroy(),再等待 manager.destroy() 和 room.disconnect()。教具配置、扩展功能、背景图及事件监听见教具插件介绍与启用。
运行项目
替换 AppIdentifier、房间 UUID、Room Token 和 uid 后,在项目目录启动开发服务器:
npx vite --host 127.0.0.1访问终端显示的本地地址,成功入房后可在主白板书写。需要展示动态 PPT 时,填入已完成转换的任务信息,再通过业务按钮调用 openDynamicPpt(manager)。部署时使用 HTTPS。
配置远端参数
需要在入房前读取远端参数时,参见动态配置。地址在创建 SDK 前设置,本地显式参数优先;读取失败回退本地参数。
声网 Whiteboard HarmonyOS SDK 提供 ArkUI 白板组件。通过 WhiteboardOptions 初始化并加入房间,使用 WhiteboardController 操作房间,使用 WhiteboardCallbacks 接收事件。
前提条件
- DevEco Studio、HarmonyOS Stage 模型工程;本版仓库以 HarmonyOS 5.0.0 / API 12 为兼容基线。
- 已开启互动白板服务,获取 AppIdentifier。
- 业务服务端已创建房间,并下发匹配房间和数据中心的 Room Token。
获取 SDK
ohpm install @shengwang/whiteboard@0.2.11添加权限
在模块 module.json5 的 module 中添加网络权限:
{
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}实现步骤
1. 创建房间
由业务服务端调用创建房间,保存返回的房间 UUID 和数据中心。
2. 生成 Room Token
由业务服务端生成 Room Token,将房间 UUID、Room Token 和用户 uid 下发给客户端。SDK Token 保存在服务端。
3. 准备控制器和回调
创建 WhiteboardController 和 WhiteboardCallbacks,在组件显示前设置回调。onRoomReady 表示已成功入房,之后可调用房间与 App 接口。以下完整示例包含这两个对象。
4. 创建组件并加入房间
import {
Whiteboard, WhiteboardOptions, WhiteboardController,
WhiteboardCallbacks, Region, SDKError, WindowParams
} from '@shengwang/whiteboard';
@Entry
@Component
struct WhiteboardPage {
private controller: WhiteboardController = new WhiteboardController();
private callbacks: WhiteboardCallbacks = new WhiteboardCallbacks();
private options: WhiteboardOptions = {
appIdentifier: 'APP_IDENTIFIER',
roomUuid: 'ROOM_UUID',
roomToken: 'ROOM_TOKEN',
uid: 'CLIENT_UID',
region: Region.CN_HZ,
writable: true,
useMultiViews: true,
windowParams: new WindowParams(),
enableAppliancePlugin: true
};
aboutToAppear(): void {
this.callbacks.setOnRoomReady(() => {
// 已加入房间,可开始使用 controller 操作白板。
});
this.callbacks.sdkSetupFail = (error: SDKError) => {
console.error(error.message);
// 业务侧重新创建组件,完成 SDK 初始化和重新入房。
};
this.callbacks.setOnRoomPhaseChanged((phase) => {
console.info(`room phase: ${phase}`);
});
}
build() {
Column() {
Whiteboard({
options: this.options,
controller: this.controller,
callbacks: this.callbacks,
webDebug: false
}).width('100%').height('100%');
}.width('100%').height('100%');
}
}appIdentifier、roomUuid、roomToken、uid、region 为必填字段。region 必须与创建房间的服务区域一致,writable 未传时映射为 true,useMultiViews/userCursor/enableAppliancePlugin 未显式提供时允许继承动态配置;未启用动态配置时使用内建默认。
必须把回调对象传给组件的 callbacks 参数;本版组件实际使用此参数,不能只填写 options.callbacks。组件加载后自动初始化 SDK 并入房,本版没有业务调用的 joinRoom() 方法。等待 onRoomReady 后再操作房间。
5. 接入多窗口
Window Manager 已通过内嵌 Bridge 集成。组件创建前设置 WhiteboardOptions.useMultiViews=true,窗口显示参数放在 windowParams。步骤 4 的示例已包含这两项:
// 在组件创建前配置,随后通过 Whiteboard 的 options 参数传入。
this.options.useMultiViews = true;
const windowParams = new WindowParams();
windowParams.setContainerSizeRatio(9 / 16);
this.options.windowParams = windowParams;组件初始化并入房后自动挂载窗口管理器,业务通过 Controller 调用 App 和页面接口。详细配置见多窗口与统一课件控制。
6. 接入动态 PPT
内嵌 Bridge 已注册 app-slide。业务服务端完成转换后,在 onRoomReady 回调之后,通过 controller.addApp 创建动态 PPT 窗口:
import { WindowAppParam } from '@shengwang/whiteboard';
// 放在 WhiteboardPage 的业务方法中;入房成功后由按钮调用。
async openDynamicPpt(): Promise<void> {
const slide: WindowAppParam = {
kind: 'Slide',
options: {
title: '教学课件.pptx',
scenePath: '/slides/lesson-1'
},
attributes: {
taskId: 'CONVERSION_TASK_UUID',
url: 'https://convertcdn.netless.link/dynamicConvert'
}
};
try {
const appId = await this.controller.addApp(slide);
console.info(`动态 PPT 窗口 ID:${appId}`);
} catch (error) {
console.error(`创建课件窗口失败:${error}`);
}
}taskId 使用已完成转换的任务 UUID,url 是资源地址前缀(末尾不带 /,不是 PPT 源文件地址)。options.scenePath 必须是以 / 开头的场景目录,同一房间内每个 App 使用不同目录。创建 App 需要可写权限;房间中已存在的课件会同步显示,不要在每次入房时重复插入。返回 ID 不表示课件资源与首帧全部加载完成。课件操作见新版 API 与多窗口课件控制。
7. 开启新教具
创建组件前同时启用多 View 与教具插件;步骤 4 的示例已开启:
this.options.useMultiViews = true;
this.options.enableAppliancePlugin = true;SDK 已内嵌 Appliance Plugin 和 Worker,业务继续使用 Controller 的原生方法设置 Pencil、Selector、Eraser、Shape、Text 等教具,同一房间各端应一致开启。入房前的插件参数放在 WhiteboardOptions.appliancePluginOptions,自定义教具、背景图和 Auto Shape 见教具插件介绍与启用。
上述开关在组件初始化前配置;已入房后修改 options 不用于动态开启插件。
离开房间
在组件仍然挂载时调用并等待 controller.disconnect(),完成后再隐藏或销毁白板组件。组件消失时会解除 Controller 与 Bridge 的绑定。异步接口应处理 Promise rejection。
后续功能
0.2.11 没有公开的回放 Player、SyncedStore 或自定义 App 注册入口。业务应依据 Harmony 实际公开接口集成。
等待退出完成
调用 await controller.leaveRoom() 等待所属房间清理;disconnect() 保留为兼容入口并委托相同退出流程。重复退出复用清理结果。退出失败时先处理错误,避免立刻发起下一次入房;组件解绑不能当作房间已经退出的通知。动态配置接入和缺省规则见动态配置。