Getting started

Note

This document is applicable to the following platforms: iOS, Android.

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.

Prerequisites

ZegoSuperBoard SDK needs to be used with ZegoExpress-Video SDK, please follow this webpage o obtain and Integrate ZegoExpress-Video SDK.
A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.

Prepare the environment

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

React Native is in version 0.60 or later.
The iOS system is in version 9.0 or later and supports audio and video iOS devices or simulators (real devices are recommended).
An Android device or emulator with Android version no less than 5.0 and supporting audio and video (real devices are recommended). If it is a real device, please turn on the "Allow debugging" option.
iOS/Android devices have been connected to the Internet.
Install Node.js. It is recommended to use the long-term support version shown on the homepage of its official website.

(optional) Create a new project

Note

If you already have a project, you can skip this step.

If you need to know how to create a React Native project, please refer to the official React Native documentation Setting up the development environment.

Project configuration

iOS

Install CocoaPods. For installation methods and FAQs, please refer to CocoaPods Installation Guide .
Execute the pod install command in the project's iOS directory to install the SDK.

Android

Add dependencies

Super Board SDK depends on the following modules. Add the following code under the dependencies node in the "your project/android/app/build.gradle" file:

implementation 'androidx.appcompat:appcompat:1.3.1'
implementation 'com.google.android.material:material:1.4.0'
implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.4.30'

implementation 'androidx.appcompat:appcompat:1.3.1'
implementation 'com.google.android.material:material:1.4.0'
implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.4.30'

Setting permissions

To add a permission statement, open the "your project/android/app/src/main/AndroidManifest.xml" file and add the following content:

To add a permission statement, open the "app/AndroidManifest.xml" file and add the following content:

    <!-- Permissions that SDK must use -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <!-- Permissions that SDK must use -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

The permissions are explained as follows:

Permissions	Necessity	Permission description	Reason for need
INTERNET	Necessary permissions	Network access permissions	The basic functions of the SDK can only be used when connected to the Internet.
ACCESS_WIFI_STATE	Necessary permissions	Get current WIFI status permissions	The SDK will perform different operations according to changes in the network status. For example, when the network is reconnected, the SDK will internally restore the status when the network was disconnected, and the user does not need to perform additional operations.
ACCESS_NETWORK_STATE	Necessary permissions	Get the current network status permissions	The SDK will perform different operations according to changes in the network status. For example, when the network is reconnected, the SDK will internally restore the status when the network was disconnected, and the user does not need to perform additional operations.
WRITE_EXTERNAL_STORAGE	Necessary permissions	Built-in SD card write permissions	If you need to use a media player or sound player to load media resource files in Android external storage, you need to apply for this permission, otherwise the SDK cannot load the resources.
READ_EXTERNAL_STORAGE	Necessary permissions	Built-in SD card read permission	The SDK will save logs and related configuration files in the built-in SD card.

Preventing confusion

In the “your project/android/app/proguard-rules.pro” file, add the -keep class configuration for the SDK, which will prevent obfuscation of the SDK public class names.

In the proguard-rules.pro, add the -keep class configuration for the SDK, which prevents obfuscation of SDK public class names.

-keep class im.zego.zegowhiteboard.**{*;}
-keep class im.zego.zegodocs.**{*;}
-keep class im.zego.superboard.**{*;}

-keep class im.zego.zegowhiteboard.**{*;}
-keep class im.zego.zegodocs.**{*;}
-keep class im.zego.superboard.**{*;}

Integrate the SDK

Go to the root directory of your project through the terminal and install the SDK through the yarn/npm command (Contact the ZEGOCLOUD technical support to know the command).

Import the SDK

Use the following method to import Express Video SDK and Super Board SDK.

import ZegoExpressEngine from 'zego-express-engine-whiteboard-reactnative';
import ZegoSuperBoardManager, {ZegoSuperBoardRenderView} from 'zego-superboard-reactnative';

import ZegoExpressEngine from 'zego-express-engine-whiteboard-reactnative';
import ZegoSuperBoardManager, {ZegoSuperBoardRenderView} from 'zego-superboard-reactnative';

Implement the Super Board

1. Initialize the SDK

Initialize the ZEGO Express Video SDK

Call the createEngineWithProfile interface of Express Video SDK and pass in the applied AppID and AppSign Parameters "appID" and "appSign" create an engine singleton object.

If you need to register a callback method, developers can implement Express Video SDK's ZegoEventListener, you can create an engine by calling some of the methods in on interface after creating the engine.

// Use common scenarios
const profile = {
    appID: YOURAPPID,
    // AppSign can be obtained through [Console](https://console.zegocloud.com/account/login)
    appSign: 'YOURAPPSIGN',
    scenario : 0
};

ZegoExpressEngine.createEngineWithProfile(profile)

// Use common scenarios
const profile = {
    appID: YOURAPPID,
    // AppSign can be obtained through [Console](https://console.zegocloud.com/account/login)
    appSign: 'YOURAPPSIGN',
    scenario : 0
};

ZegoExpressEngine.createEngineWithProfile(profile)

Initialize ZegoSuperBoard SDK

Get the ZegoSuperBoard instance using the getInstance method of ZegoSuperBoardManager.

const superboardConfig = {
  appID: YOURAPPID,
  appSign: 'YOURAPPSIGN',
};

initSuperboad = async () => {
    // Initialize ZegoSuperBoard SDK
    const superboard_init_res = await ZegoSuperBoardManager.init(superboardConfig);
    // Initialization result
    console.log('Result', superboard_init_res);
  };
initSuperboad()

const superboardConfig = {
  appID: YOURAPPID,
  appSign: 'YOURAPPSIGN',
};

initSuperboad = async () => {
    // Initialize ZegoSuperBoard SDK
    const superboard_init_res = await ZegoSuperBoardManager.init(superboardConfig);
    // Initialization result
    console.log('Result', superboard_init_res);
  };
initSuperboad()

Warning

Please initialize ZegoExpress-Video SDK and ZegoSuperBoard SDK successfully before calling the login room interface.

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

Warning

The SuperBoard automatically realizes the multi-end synchronization capability, and only needs to refresh the local UI logic in the remote notification callback.

on: Register a callback event and specify the listening event name through event.

// Commonly used SuperBoard related callbacks
// SuperBoard automatically implements multi-end synchronization capabilities, and only needs to refresh the local UI logic in the remote notification callback.
// Listen for error callbacks. SDK internal errors are thrown through this callback, except for errors returned directly in the interface.

    // Get Instance
    var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
    zegoSuperBoard.on('error', function(errorData) {
        // Error code, error message
        console.log(errorData.code, errorData.message)
    });

    // Listen for whiteboard page turning and scrolling
    zegoSuperBoard.on("scrollChange", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList, currentPage, pageCount) {}
    );

    // Listen for new remote whiteboards
    zegoSuperBoard.on("remoteSuperBoardSubViewAdded", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList) {});

    // Listen for remote destruction of whiteboard
    zegoSuperBoard.on("remoteSuperBoardSubViewRemoved", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList) {});

    // Listen for remote switching whiteboard
    zegoSuperBoard.on("remoteSuperBoardSubViewSwitched", function (uniqueID) {});

    // Listen for remote whiteboard permission changes
    zegoSuperBoard.on("remoteSuperBoardAuthChanged", function (data) {});

    // Listen for remote whiteboard element permission changes
    zegoSuperBoard.on("remoteSuperBoardGraphicAuthChanged", function (data) {});

// Commonly used SuperBoard related callbacks
// SuperBoard automatically implements multi-end synchronization capabilities, and only needs to refresh the local UI logic in the remote notification callback.
// Listen for error callbacks. SDK internal errors are thrown through this callback, except for errors returned directly in the interface.

    // Get Instance
    var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
    zegoSuperBoard.on('error', function(errorData) {
        // Error code, error message
        console.log(errorData.code, errorData.message)
    });

    // Listen for whiteboard page turning and scrolling
    zegoSuperBoard.on("scrollChange", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList, currentPage, pageCount) {}
    );

    // Listen for new remote whiteboards
    zegoSuperBoard.on("remoteSuperBoardSubViewAdded", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList) {});

    // Listen for remote destruction of whiteboard
    zegoSuperBoard.on("remoteSuperBoardSubViewRemoved", function (name, createTime, fileID, fileType, uniqueID, whiteboardIDList) {});

    // Listen for remote switching whiteboard
    zegoSuperBoard.on("remoteSuperBoardSubViewSwitched", function (uniqueID) {});

    // Listen for remote whiteboard permission changes
    zegoSuperBoard.on("remoteSuperBoardAuthChanged", function (data) {});

    // Listen for remote whiteboard element permission changes
    zegoSuperBoard.on("remoteSuperBoardGraphicAuthChanged", function (data) {});

3. Log in to the room

You can call the loginRoom interface of Express Video SDK to log in to the room. If the room does not exist, the room will be created and logged in when this interface is called.

The parameters of roomID and user are generated locally by you, but they need to meet the following conditions:：

Within the same AppID, "roomID" must be globally unique.
Within the same AppID, "userID" must be globally unique. It is recommended that developers associate "userID" with their own business account system.

// Log in to room
ZegoExpressEngine.instance().loginRoom('room1', {'userID': 'id1', 'userName': 'user1'});

// Log in to room
ZegoExpressEngine.instance().loginRoom('room1', {'userID': 'id1', 'userName': 'user1'});


// The following are commonly used room-related callbacks

ZegoExpressEngine.instance().on('roomStateUpdate', (roomID, state, errorCode, extendedData) => {
  // Room status update callback. After logging in to the room, when the room connection status changes (such as room disconnection, login authentication failure, etc.), the SDK will notify through this callback
}); ;


// The following are commonly used room-related callbacks

ZegoExpressEngine.instance().on('roomStateUpdate', (roomID, state, errorCode, extendedData) => {
  // Room status update callback. After logging in to the room, when the room connection status changes (such as room disconnection, login authentication failure, etc.), the SDK will notify through this callback
}); ;

4. Create a whiteboard

A Super Board can be used to create a common 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.

Before creating a whiteboard, ensure that the login is successful, that is, you can only create a whiteboard after logging in to the room and returning true.

Create a common whiteboard

Define an area to mount the whiteboard

<ZegoSuperBoardRenderView ref={refContainer} style={{ height: 500, width: 300 } />

<ZegoSuperBoardRenderView ref={refContainer} style={{ height: 500, width: 300 } />

Warning

The width and height of the area where the whiteboard is mounted must not be less than 0.

Create a common whiteboard

// You can only create a whiteboard after successfully logging into the room.

// After successful login, this area needs to be passed in
const tag = findNodeHandle(refContainer.current);
    await ZegoSuperBoardManager.setContainerView({
      reactTag: tag,
    });

// Get instance
var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
const res = await zegoSuperBoard.createWhiteboardView({
    name: 'test whiteboard', // The name of the created whiteboard
    pageCount: 5, // Number of whiteboard pages created
    perPageWidth: 960, // page width
    perPageHeight: 540,// page height
});

// You can only create a whiteboard after successfully logging into the room.

// After successful login, this area needs to be passed in
const tag = findNodeHandle(refContainer.current);
    await ZegoSuperBoardManager.setContainerView({
      reactTag: tag,
    });

// Get instance
var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
const res = await zegoSuperBoard.createWhiteboardView({
    name: 'test whiteboard', // The name of the created whiteboard
    pageCount: 5, // Number of whiteboard pages created
    perPageWidth: 960, // page width
    perPageHeight: 540,// page height
});

Warning

At most 50 whiteboards can be created in a room. The whiteboard creation will fail if the room already has 50 whiteboards.
To obtain the current number of whiteboards in a room, call the querySuperBoardSubViewList method.

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

6. 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.getInstance().querySuperBoardSubViewList().
// Get Instance
var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
const result = await zegoSuperBoard.destroySuperBoardSubView(uniqueID)

// 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.getInstance().querySuperBoardSubViewList().
// Get Instance
var zegoSuperBoard = ZegoSuperBoardManager.getInstance()
const result = await zegoSuperBoard.destroySuperBoardSubView(uniqueID)

7. Leave the room

Call the logoutRoom interface of ZegoExpressEngine to leave the room.

engine.logoutRoom(roomID);

engine.logoutRoom(roomID);

8. Deinitialize the SDK

Deinitialize the ZegoSuperBoard SDK

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

ZegoSuperBoardManager.getInstance().unInit();

ZegoSuperBoardManager.getInstance().unInit();

Deinitialize the ZEGO Express Video SDK

If you no longer need the capabilities of 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();

ZegoExpressEngine.destroyEngine();