Create a super board

Basic concepts

• ZegoExpress-Video SDK: Audio and video interactive SDK of ZEGO, which can provide the real-time signaling transmission capability required by the Super Board. The Super Board SDK must be used together with this SDK.
• Super Board SDK and ZegoSuperBoard SDK: Both refer to the SDKs that provide the ZEGO Super Board service, that is, ZegoSuperBoard.
• ZegoSuperBoardView: Whiteboard view used by developers for presentation during code implementation.
• ZegoSuperBoardSubView: Subset of ZegoSuperBoardView, which is actually created by developers. ZegoSuperBoardView will automatically presents the newly created ZegoSuperBoardSubView or specified ZegoSuperBoardSubView using switchSuperBoardSubView.
• Common whiteboard: Whiteboard created by specifying the width, height, and number of pages, and drawn by a user in real time on the specified whiteboard canvas.
• File whiteboard: Whiteboard created based on a file. The width, height and number of pages of the whiteboard are determined by the file, meeting the business requirements for drawing diagram elements on the file.

Prerequisites

• The ZegoSuperBoard SDK needs to be used together with the matching ZegoExpress-Video SDK. Therefore, if the ZegoExpress-Video SDK has been integrated, you need to delete the old SDK package and refer to this page to re-integrate the SDK package to avoid an initialization failure due to SDK version mismatch.
• Create a project in the ZEGOCLOUD Admin Console and get the AppID and AppSign of your project.

Prepare the environment

Before integrating the ZegoSuperBoard SDK, ensure that the development environment satisfies the following requirements:

• Xcode is in version 7.0 or later.
• The iOS system is in version 11.0 or later and supports audio and video iOS devices or simulators (real devices are recommended).

• iOS devices have been connected to the Internet.

Integrate the SDK

Optional: Create a project

This step takes how to create a new project as an example. If the project is integrated into an existing project, skip this step.

1. Start Xcode. In the Welcome to Xcode window, select Create a new Xcode project or select File > New > Project. In the table form that is displayed, select the iOS platform and select Application > App.

   

2. Fill in the table form, select the desired options to configure a project, and click Next.

Product Name and Organization Identify must be provided to create Bundle Identify that identifies the app in the entire system.

3. Select the project storage path and click Create to create a project.
   

Import the SDK

You can integrate the SDK using either of the following methods:

Method 1: Use CocoaPods for automatic integration

1. Install the CocoaPods. For details about the installation method and common issues, refer to CocoaPods Installation Guide .

2. Open the terminal, visit the root directory of the project, and run pod init to create the Podfile file.

3. Open the Podfile file and add pod 'ZegoSuperBoard'.

4. Run pod install to install the SDK.

Method 2: Copy the SDK file for manual integration

1. Refer to SDK downloads to download and extract the latest version of SDK.

2. Manually copy the SDK Dynamic Library file to the project directory.

3. Open the Xcode, select File > Add Files to "xxx" (xxx indicates the project name), and add the SDK Library file to the project.

   

4. Select TARGETS > General > Frameworks,Libraries,and Enbedded Content, add ZegoSuperBoard.xcframework, ZegoWhiteboardView.xcframework, ZegoDocsView.xcframework, and ZegoExpressEngine.xcframework, and set Embed to Embed & Sign.

   

5. Select TARGET > General > Deployment Info and set the version to 9.0 or later.

   

Initialize the SDK

Initialize the ZEGO Express Video SDK

To create a singleton instance of the ZegoExpressEngine class, call the createEngineWithProfile method with the AppID of your project.

To receive callbacks, implement an event handler object that conforms to the ZegoEventHandler protocol（for example, self), and then pass the implemented event handler object to the createEngineWithProfile method as the eventHandler parameter. Alternatively, you can pass nil to the createEngineWithProfile method as the eventHandler parameter for now, and then call the method setEventHandler to set up the event handler after creating the engine.

/**
*  appID: The AppID value you get from the ZEGOCLOUD Admin console.
*  The AppID ranges from 0 - 4294967295.
* appSign: The AppSign you get from the ZEGOCLOUD Admin console.
* scenario: the scenario you use. [ZegoScenarioGeneral] refers to the general scenario. 
*/
ZegoEngineProfile *profile = [[ZegoEngineProfile alloc] init];
profile.appID = <#appID#>;
profile.appSign = <#appSign#>;
profile.scenario = ZegoScenarioGeneral;
// Create a ZegoExpressEngine instance and set eventHandler to [self]. If eventHandler is set to [nil], no callback will be received. You can set up the event handler later by calling the [-setEventHandler:] method.
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];

Initialize the ZegoSuperBoard SDK

Use the initWithConfig method in ZegoSuperBoardManager to initialize the ZegoSuperBoard SDK.

If errorCode in the callback onInit is 0, initialization is successful and more operations can be performed. For details about errorCode, refer to Common Error Codes.

unsigned int appID = ;  /** In the format of 123456789L.*/
// Contact us to get the appsign
NSString * appSign = ;  /** 64 characters in the format of "0123456789012345678901234567890123456789012345678901234567890123" */.

// Create the initialization configuration class ZegoSuperBoardInitConfig.
ZegoSuperBoardInitConfig * config = [ZegoSuperBoardInitConfig new];
config.appID = appID; // Assign the value to appID.
config.appSign = appSign; // Assign the value to appSign.

// Set ZegoSuperBoardManager listening for, which must be performed before the login to a room.
[ZegoSuperBoardManager sharedInstance].delegate = self;

[[ZegoSuperBoardManager sharedInstance] initWithConfig:config complete:^(ZegoSuperBoardError errorCode) {
    if (errorCode == ZegoSuperBoardSuccess) {
         /** Initialization succeeded */
    } else {
        /** Initialization failed. */
    }
}];

Listen for event callbacks

Based on the actual application needs, you can listen for the concerned event callbacks after the ZegoSuperBoard SDK is initialized. The callbacks include error reminders, adding whiteboard files remotely, deleting whiteboard files remotely, and switching whiteboard files remotely.

• onError: Error code thrown by the SDK. For details about errorCode, refer to Common Error Codes.
• onRemoteSuperBoardSubViewAdded: Callback for remotely adding a file whiteboard.
• onRemoteSuperBoardSubViewRemoved: Callback for remotely destroying a file whiteboard.
• onRemoteSuperBoardSubViewSwitched: Callback for remotely switching a file whiteboard.

// Comform to the ZegoSuperBoardManagerDelegate protocol to handle related event callbacks.
@interface ViewController () <ZegoSuperBoardManagerDelegate>
// ······
@end

@implementation ViewController

// Common SuperBoard-related callbacks
// The SuperBoard automatically realizes the multi-terminal synchronization capability, and only needs to refresh the local UI logic in the remote notification callback.

- (void)onError:(ZegoSuperBoardError)error
{
    //Error code thrown by the SDK. You can remind users of some abnormalities based on the error codes.
}
- (void)onRemoteSuperBoardSubViewAdded:(ZegoSuperBoardSubViewModel *)model
{
     //Callback for remotely adding a whiteboard. Update the displayed UI content based on the information in the model, such as the whiteboard name.
}
- (void)onRemoteSuperBoardSubViewRemoved:(ZegoSuperBoardSubViewModel *)model{
     //Callback for remotely deleting a whiteboard
    //After receiving a notification, update the UI content based on the current [ZegoSuperBoardManager sharedInstance].superBoardView.currentSuperBoardSubView, for example, update the whiteboard name that is currently displayed.
}
- (void)onRemoteSuperBoardSubViewSwitched:(NSString *)uniqueID
{
    //Callback for remotely switching a whiteboard
    //After receiving a notification, update the UI content based on the current [ZegoSuperBoardManager sharedInstance].superBoardView.currentSuperBoardSubView, for example, update the whiteboard name that is currently displayed.
}

@end

Log in to a room

To log in to a room, call the loginRoom method.

- (void)loginRoom {
    // The roomID must be generated by you and needs to be globally unique. Users need to use the same roomID to join the same room to talk.
    NSString *roomID = @"room1";

    // The ZegoUser constructor public userWithUserID sets "userName" to the same as the passed parameter "userID". userID and userName cannot be null; otherwise, the login to the room will fail. 
    // The userID must be generated by you and needs to be globally unique. 
    ZegoUser *user = [ZegoUser userWithUserID:@"user1"];

    // onRoomUserUpdate callback can be received only by passing in a ZegoRoomConfig whose "isUserStatusNotify" parameter value is "true".
    ZegoRoomConfig *roomConfig = [[ZegoRoomConfig alloc] init];

    roomConfig.isUserStatusNotify = YES;
    // Log in to a room.
    [[ZegoExpressEngine sharedEngine] loginRoom:roomID user:user config:roomConfig callback:^(int errorCode, NSDictionary * _Nullable extendedData) {
        // (Optional callback) The result of logging in to the room. If you only pay attention to the login result, you can use this callback.
        if (errorCode == 0) {
            NSLog(@"Login successful.");
        } else {
            // Login failed. For more details, see the doc [Error codes].
            NSLog(@"Login failed. ");
        }
    }];
}

Optional: Renew the Token when it expires

- (void)onRoomTokenWillExpire:(int)remainTimeInSecond roomID:(NSString *)roomID {

    NSString * token = @“”;// The token you generated on your app server.

    [[ZegoExpressEngine sharedEngine] renewToken:token roomID:roomID];
    [[ZegoSuperBoardManager sharedInstance] renewToken:token];
}

Add a whiteboard view

After logging in to a room, directly add ZegoSuperBoardView to your business scenario view. The sample code is as follows:

ZegoSuperBoardView *superBoardView = [ZegoSuperBoardManager sharedInstance].superBoardView;
if (superBoardView != null) {
// Add ZegoSuperBoardView to the specified view (the boardContainer View in the Demo is used as an example).
    superBoardView.frame = self.currentContainer.bounds;
    [self.currentContainer addSubview:superBoardView];
}

Create a whiteboard

A Super Board can be used to create a common whiteboard or a file whiteboard.

• Common whiteboard: Whiteboard created by specifying the width, height, and number of pages, and drawn by a user in real time on the specified whiteboard canvas.
• File whiteboard: Whiteboard created based on a file. The width, height and number of pages of the whiteboard are determined by the file, meeting the business requirements for drawing diagram elements on the file.

Before creating a whiteboard, ensure that the login is successful. You are advised to call the API for creating a common whiteboard or file whiteboard in the callback for successful login.

// Before creating a whiteboard, ensure that the login to a room is successful, that is, ensure that the room callback state is ZegoRoomStateConnected.
- (void)onRoomStateUpdate:(ZegoRoomState)state errorCode:(int)errorCode extendedData:(NSDictionary *)extendedData roomID:(NSString *)roomID {

    if (state == ZegoRoomStateConnected && errorCode == 0) {
     // Login to a room is successful. You can create a whiteboard only after the login is successful.
     // You can store the code for creating a common whiteboard or file whiteboard here to ensure that the whiteboard is created only after the login to the room is successful. Alternatively, you can use other methods to ensure that a whiteboard is created only after the login is successful.

    }
}

• Create a common whiteboard

// To create a whiteboard, you need to construct the ZegoCreateWhiteboardConfig configuration class. The field descriptions are as follows:
ZegoCreateWhiteboardConfig * config = [ZegoCreateWhiteboardConfig new];
// Whiteboard name
config.name = @"one test whiteboard";
// Page count of a whiteboard
config.pageCount = 5;
// Width of one page of whiteboard
config.perPageWidth = 16;
// Height of one page of whiteboard
config.perPageHeight = 9;
// Create a whiteboard
[[ZegoSuperBoardManager sharedInstance] createWhiteboardView:config complete:^(ZegoSuperBoardError errorCode, ZegoSuperBoardSubViewModel *model) {
 // Create a whiteboard callback  
 // After the creation, update the UI based on the current [`ZegoSuperBoardManager sharedInstance`].superBoardView.currentSuperBoardSubView information. For example, update the whiteboard name that is currently displayed.
      if (errorCode == ZegoSuperBoardSuccess) {
            /** Creation succeeded. */
      } else {
            /** Creation failed. */
      }
}];

• Create a file whiteboard

Before creating a file whiteboard, obtain fileID of the file. Refer to Manage shared files to upload the file.

// To create a file whiteboard, you need to construct the ZegoCreateFileConfig configuration class.
ZegoCreateFileConfig * config = [ZegoCreateFileConfig new];
// fileID of the file, which can be obtained after the file is successfully uploaded
config.fileID = fileID;
__weak typeof(self) weakSelf = self;
[[ZegoSuperBoardManager sharedInstance] createFileView:config complete:^(ZegoSuperBoardError errorCode, ZegoSuperBoardSubViewModel *model) {
 // Create a file whiteboard callback    
 // After the creation, update the UI based on the current [`ZegoSuperBoardManager sharedInstance`].superBoardView.currentSuperBoardSubView information. For example, update the file name that is currently displayed.
      if (errorCode == ZegoSuperBoardSuccess) {
            /** Creation succeeded. */
      } else {
            /** Creation failed. */
      }

}];

Verify whiteboard creation

Use multiple devices to run the preceding project and log in to the same room ID. Press and move with your finger within the range of ZegoSuperBoardView on any device. Then the graffiti effect is displayed on ZegoSuperBoardView of the device.

Destroy a whiteboard

// After a whiteboard is destroyed, the SDK will automatically switch to another whiteboard. The displayed whiteboard is the previous one of the destroyed whiteboard.

// subViewModel is a model in the whiteboard sharing list [ZegoSuperBoardManager sharedInstance].superBoardSubViewModelList.
[[ZegoSuperBoardManager sharedInstance] destroySuperBoardSubView:subViewModel.uniqueID complete:^(ZegoSuperBoardError errorCode) {
 // Destroy a whiteboard callback    
 // After the destruction, update the UI based on the current [`ZegoSuperBoardManager sharedInstance`].superBoardView.currentSuperBoardSubView information. For example, update the whiteboard name that is currently displayed.
      if (errorCode == ZegoSuperBoardSuccess) {
            /** Destroyed */
      } else {
            /** Destruction failed. */
      }

}];

Leave the Room

Call the logoutRoom interface of ZegoExpressEngine to leave the room.

[[ZegoExpressEngine sharedEngine] logoutRoom:@"roomID"];

Deinitialize the SDK

Deinitialize the ZegoSuperBoard SDK

Call the unInit method of ZegoSuperBoardManager to deinitialize the ZegoSuperBoard SDK.

[[ZegoSuperBoardManager sharedInstance] unInit];

Deinitialize the ZEGO Express Video SDK

If you no longer need the capabilities of the ZEGO Express Video SDK, you can call the destroyEngine method of ZegoExpressEngine to destroy the engine and release resources such as microphone, camera, memory, CPU, etc.

[ZegoExpressEngine destroyEngine:^{

}];