# 加入白板房间 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网互动白板房间提供丰富的编辑工具，支持展示静态图片、动态 PPT、H5 课件等多种格式的文件，不同终端用户能在白板上实时展示想法，轻松实现多人互动协作。 本文介绍如何建立一个简单的项目，使用声网互动白板 SDK 加入房间并实现基础的白板功能。 ## 技术原理 [#技术原理-1] 下图展示了加入声网互动白板房间的基本流程。 当你的 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 以加入互动白板房间。 ## 前提条件 [#前提条件-1] - Xcode 10.10+ - CocoaPods 接入：iOS 10.0+；SwiftPM 接入：iOS 12.0+ - CocoaPods [最新版本](https://cocoapods.org/)。 - 有效的声网[开发者账号](/zh-CN/introduction/quickstart)。 - 已在声网控制台[开启互动白板服务](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/setup-and-access/enable-service)并获取[白板项目的 AppIdentifier 和 SDK Token](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。 ## 创建项目 [#创建项目] 参考以下步骤在 Xcode 中创建一个 Single View App。 创建 Objective-C 项目 创建 Swift 项目 创建一个 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`: ```objc #import ``` ## 获取 SDK [#获取-sdk-1] 1. 在 Terminal 里进入项目所在路径。运行以下命令创建 `Podfile` 文件。项目路径下会出现一个 `Podfile` 文本文件。 ```shell pod init ``` 2. 在生成的 `Podfile` 文件中添加如下内容： ```ruby platform :ios, '10.0' target 'Whiteboard' do pod 'Whiteboard', '2.16.147' end ``` 3. 运行以下命令安装 SDK： ```shell pod install ``` 安装完成后，你可以点击打开项目的 `Whiteboard.xcworkspace` 文件，对项目进行后续编辑。 :::info[信息] 对于中国大陆用户，如果在执行 `pod install` 命令时由于网络原因失败，可以使用 [TUNA 镜像源](https://mirrors.tuna.tsinghua.edu.cn/help/CocoaPods/)。 ::: ## 实现步骤 [#实现步骤-1] 现在，我们已经将声网互动白板 SDK 集成到项目中了。接下来我们要调用声网互动白板 SDK 提供的核心 API 实现基础的白板功能。 ### 1. 创建房间 [#1-创建房间-1] 在 App 客户端加入互动白板房间前，你需要在 App 服务端调用互动白板服务端 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-1] 创建房间并获取新建房间的 `uuid` 后，你需要在 App 服务端生成 Room Token 并下发给 App 客户端。当 App 客户端加入房间时，声网互动白板服务端会使用该 Token 对其鉴权。 你可以通过以下方式在 App 服务端生成 Room Token： - 使用代码生成 Room Token，详见[在 App 服务端生成 Token](/zh-CN/realtime-media/whiteboard/whiteboard-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 ``` ### 3. 创建白板视图 [#3-创建白板视图] 创建 `WhiteBoardView` 并添加到页面，设置合适的显示尺寸。以下完整示例的 `setupViews` 方法负责这一步。 ### 4. 初始化 SDK 并加入房间 [#4-初始化-sdk-并加入房间-1] 编辑 `ViewController.m`，实现从添加 View、初始化 SDK 到加入房间的基本操作。你需要传入以下参数： - `appIdentifier`：互动白板项目的唯一标识符。详见[获取 AppIdentifier](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。 - `uuid`：房间的唯一标识符。详见[创建房间](#1-创建房间-1)。 - `uid`：用户的唯一标识符，字符串格式，长度不能超过 1024 字节。如果你使用 2.15.0 或之后版本的 SDK，必须传入该参数；如果你使用 2.15.0 之前版本的 SDK，则不需要传入该参数。 - `roomToken`：用于鉴权的 Room Token。生成该 Room Token 使用的房间 UUID 必须和上面的房间 UUID 一致。详见[生成 Room Token](#2-生成-room-token-1)。 - `region`：数据中心，必须和创建房间时设置的数据中心一致。 ```objc tab="Objective-C" // ViewController.m // WhiteBoard #import "ViewController.h" #import @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 commonDelegate; @property(nonatomic, weak, nullable) id 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 ``` ```swift tab="Swift" // 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. 接入多窗口 [#5-接入多窗口-1] SDK 已通过内嵌 Bridge 集成 Window Manager。创建 `WhiteSDK` 前配置多 View，入房前配置 `WhiteRoomConfig.windowParams`。步骤 4 的完整示例已包含这些配置： ```objc tab="Objective-C" // 创建 WhiteSDK 前设置。 self.sdkConfig.useMultiViews = YES; // joinRoomWithConfig 前设置。 self.roomConfig.windowParams = [WhiteWindowParams new]; ``` ```swift tab="Swift" // 创建 WhiteSDK 前设置。 self.sdkConfig?.useMultiViews = true // joinRoom 前设置。 self.roomConfig?.windowParams = WhiteWindowParams() ``` 入房后 SDK 在 `WhiteBoardView` 内挂载窗口管理器。配置和控制方法见[新版 API 与多窗口课件控制](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-page-control)。 ### 6. 接入动态 PPT [#6-接入动态-ppt-1] 内嵌 Bridge 已注册 app-slide。在入房成功后或业务“打开课件”按钮中，创建 `WhiteAppParam` 并调用 `WhiteRoom.addApp`： ```objc tab="Objective-C" 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"); } }]; ``` ```swift tab="Swift" 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 不表示所有资源和首帧已加载。转换和展示方式见[展示文件](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/courseware-integration)。 ### 7. 开启新教具 [#7-开启新教具-1] 创建 SDK 前同时启用多 View 与新教具。步骤 4 的完整示例已开启： ```objc tab="Objective-C" self.sdkConfig.useMultiViews = YES; self.sdkConfig.enableAppliancePlugin = YES; ``` ```swift tab="Swift" self.sdkConfig?.useMultiViews = true self.sdkConfig?.enableAppliancePlugin = true ``` Appliance Plugin 与 Worker 资源已随 SDK 内嵌，继续使用 `WhiteRoom.setMemberState` 等原生方法配置 Pencil、Selector、Eraser、Shape、Text 等教具。同房间各端应一致开启。入房前可通过 `WhiteRoomConfig.appliancePluginOptions` 传入插件参数，接入细节见[教具插件介绍与启用](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/overview)。 这些开关必须在 SDK 初始化前设置；已经入房后修改配置对象不会开启插件。 ## 编译并运行项目 [#编译并运行项目-1] 在 Xcode 中编译并在模拟器或真机上运行项目。入房成功后可在白板书写，并使用步骤 6 的原生 API 打开动态 PPT。 ## 等待退出完成 [#等待退出完成] Whiteboard iOS 2.16.147 可用 `leaveRoomWithCompletionHandler:` 等待所属 Room 退出，完成回调的 NSError 为空表示成功。先处理退出结果，再销毁宿主或继续下一次入房。配置地址和参数优先级见[动态配置](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/dynamic-config)。