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 describes how to create a basic project and use the Agora Interactive Whiteboard SDK to implement basic whiteboard features.
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:
This section describes how to create Single View App in Xcode.
To create an Objective-C project in Xcode, perform the following steps
Whiteboard
.agora
.Objective-C
for Language.To create a Swift project in Xcode, perform the following steps:
Whiteboard
.agora
.Swift
for Language.Storyboard
for User Interface.The Agora Interactive Whiteboard SDK uses Objective-C. To use the Objective-C SDK in your Swift app, you need to create an Objective-C bridging header file, as follows:
Whiteboard-Bridging_Header.h
file to your project.Whiteboard-Bridging_Header.h
file:#import <Whiteboard/Whiteboard.h>
In Terminal, go to the directory of your Xcode project. Run the following command to create a Podfile
, after which you can find the Podfile
under the project directory.
pod init
Add the following lines to the Podfile
:
platform :ios, '10.0'
target 'Whiteboard' do
pod 'Whiteboard'
end
Run the following command to install the SDK:
pod install
After installation, open the Whiteboard.xcworkspace
file for further editing.
The Agora Interactive Whiteboard SDK has now been integrated into the iOS project. Next, call the core APIs in the SDK to implement basic whiteboard features.
Before an app client requests to join a room, you need to call the Interactive Whiteboard RESTful API on your app server to create a room. See Create a room (POST).
Request example
Refer to the following Node.js script to send an HTTP request:
request
module. You can run the command line npm install request
to install the module.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.
Response example
{
"uuid": "4a50xxxxxx796b", // The Room UUID
"teamUUID": "RMmLxxxxxx15aw",
"appUUID": "i54xxxxxx1AQ",
"isRecord": false,
"isBan": false,
"createdAt": "2021-01-18T06:56:29.432Z",
"limit": 0
}
After creating a room and getting the uuid
of the room, you need to generate a Room Token on your app server 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:
The following examples describe how to use the Interactive Whiteboard RESTful API to generate a Room Token.
Request example
Refer to the following Node.js script to send an HTTP request:
request
module. You can run the command line npm install request
to install the module.var request = require('request');
var options = {
"method": "POST",
// Replace <Room UUID> with your Room UUID
"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.
Response example
"NETLESSROOM_YWs9XXXXXXXXXXXZWNhNjk" // Room Token
Edit ViewController.m
to add a view, initialize the SDK, and join a room. You need to pass in the following parameters:
appIdentifier
: If you use versions earlier than v2.15.0, do not pass in uid: The unique identifier of the whiteboard project. See Get security credentials for your whiteboard project.uuid
: The unique identifier of the room. See Create a room.uid
: The unique identifier of a user in a string format. The maximum length is 1024 bytes. If you use v2.15.0 and later versions, you must pass in this parameter; if you use versions earlier than v2.15.0, do not pass in this parameter.roomToken
: The Room Token used for authentication. The Room Token must be generated using the Room UUID above. See Generate a Room Token.region
: The data center, which must be the same as the data center you chose when creating the room.// 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
// Add a view
- (void)setupViews
{
self.config = [[WKWebViewConfiguration alloc] init];
// Set the view of the whiteboard to full-screen
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)];
}
// Initialize the SDK
- (void)initSDK
{ // Pass in the App Identifier
self.sdkConfig = [[WhiteSdkConfiguration alloc] initWithApp:@"Your App ID"];
// Set the data center as Silicon Valley, US
sdkConfig.region = WhiteRegionUS;
// Initialize the SDK
self.sdk = [[WhiteSDK alloc] initWithWhiteBoardView:self.boardView config:self.sdkConfig commonCallbackDelegate:self.commonDelegate];
}
// Join a whiteboard room
- (void)joinRoom
{ // Pass in the Room UUID, uid of the user, and Room Token.
// If you use versions earlier than v2.15.0, do not pass in uid:@"user uid".
self.roomConfig = [[WhiteRoomConfig alloc] initWithUuid:@"Your UUID" roomToken:@"Your room token" uid:@"user uid"];
// Set the whiteboard tool
self.memberState = [[WhiteMemberState alloc] init];
self.memberState.currentApplianceName = AppliancePencil;
self.memberState.strokeColor = @[@255, @0, @0];
// Join the room
[self.sdk joinRoomWithConfig:self.roomConfig callbacks:self.roomCallbackDelegate completionHandler:^(BOOL success, WhiteRoom * _Nonnull room, NSError * _Nonnull error) {
if (success) {
self.room = room;
[self.room cleanScene:(NO)];
[self.room setMemberState:(self.memberState)];
NSLog(@"Successfully joined the room");
} else {
NSLog(@"Errors when joining room");
}
}];
}
// In viewDidLoad, call the corresponding functions to add a view, initialize the SDK, and join a room
- (void)viewDidLoad {
[super viewDidLoad];
[self setupViews];
[self initSDK];
[self joinRoom];
}
@end
// ViewController.swift
// Whiteboard
import UIKit
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?
// Add a view
func setupViews()
{
self.config = WKWebViewConfiguration()
// Set the view of the whiteboard to full-screen
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!)
}
// Initialize the SDK
func initSDK()
{ // Pass in the App Identifier
self.sdkConfig = WhiteSdkConfiguration(app: "Your App Indentifier")
// Set the data center as Silicon Valley, US
sdkConfig.region = WhiteRegionUS
// Initialize the SDK
self.sdk = WhiteSDK(whiteBoardView: self.boardView!, config: self.sdkConfig!, commonCallbackDelegate: self.commonDelegate)
}
// Join a whiteboard room
func joinRoom()
{
// Pass in the Room UUID, uid of a user, and Room Token.
// If you use versions earlier than v2.15.0, do not pass in uid: "user uid".
self.roomConfig = WhiteRoomConfig(uuid: "Your uuid", roomToken:"Your room token", uid: "user uid")
// Set the whiteboard tool
self.memberState = WhiteMemberState()
self.memberState?.currentApplianceName = WhiteApplianceNameKey.AppliancePencil
self.memberState?.strokeColor = [255,0,0]
// Join the room
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")
}
})
}
// In viewDidLoad, call the corresponding functions to add a view, initialize the SDK, and join a room
override func viewDidLoad() {
super.viewDidLoad()
self.setupViews()
self.initSDK()
self.joinRoom()
}
}
Build the project in Xcode, and run it on a simulator or a physical mobile device. If the project runs successfully, you can see a new page and use your mouse to write and draw on the page.
We provide an open-source sample project Whiteboard-iOS that implements the whiteboard room on GitHub. You can download the sample project and refer to the source code.