Join a Whiteboard Room

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.

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：

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

Prerequisites

• Xcode 10.10 or later
• iOS 9.0 or later
• The latest version of CocoaPods
• 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 project in Xcode

This section describes how to create Single View App in Xcode.

Create an Objective-C project

To create an Objective-C project in Xcode, perform the following steps

• Set Product Name to Whiteboard.
• Set Organization Identifier to agora.
• Select Objective-C for Language.

Create a Swift project

To create a Swift project in Xcode, perform the following steps:

• Set Product Name to Whiteboard.
• Set Organization Identifier to agora.
• Select Swift for Language.
• Select 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:

• Add a Whiteboard-Bridging_Header.h file to your project.
• Add the following import line in the Whiteboard-Bridging_Header.h file:

  #import <Whiteboard/Whiteboard.h>

Get Agora Interactive Whiteboard SDK

1. 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

2. Add the following lines to the Podfile:

   platform :ios, '10.0'
   target 'Whiteboard' do
      pod 'Whiteboard'
   end

3. Run the following command to install the SDK:

   pod install

   After installation, open the Whiteboard.xcworkspace file for further editing.

Implement whiteboard features

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.

1. Create a room

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:

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
}

2. Generate a Room Token

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:

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

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:

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

3. Initialize the SDK and join a room

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 and run the project

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.

Reference

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.