Collaborative Whiteboard and File Sharing

---

1 Introduction

1.1 Introduction

In the actual business development process, the Collaborative Whiteboard(ZegoWhiteboardView SDK) is often used with File Sharing(ZegoDocsView SDK). Under normal circumstances, ZegoWhiteboardView will be overlaid on ZegoDocsView, and then through certain logical processing, the business requirements of drawing primitives on the file can be realized.

1.2 Concept Explanation

• ZegoWhiteboardView SDK: SDK that provides ZEGO Collaborative Whiteboard service. At the same time, the ZegoWhiteboardView SDK on the Web includes the ZEGO real-time audio and video functions, which can provide the real-time signaling transmission capabilities required by the Collaborative Whiteboard.
• ZegoDocsView SDK: SDK that provides ZEGO File Sharing services.
• ZegoWhiteboardView: The ZegoWhiteboardView view used directly by the developer during the code implementation process.
• ZegoDocsView: The ZegoDocsView view used directly by developers in the code implementation process.
• File whiteboard: ZegoWhiteboardView is a view composed of overlaid on ZegoDocsView.
• Ordinary whiteboard: ZegoWhiteboardView view.

2 Prerequisites

• ZegoWhiteboardView SDK has been integrated in the project. For details, please refer to Quick Starts - Integration.

• ZegoDocsView SDK has been integrated in the project. For details, please refer to the Quick Starts - Integration of File Sharing .

• You have created a project in the ZEGO Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Management.

3 Common Usage

3.1 Initialize SDK

3.1.1 Introduce SDK

The developer introduces ZegoWhiteboardView SDK and ZegoDocsView SDK into the project.

Method 1: Download the SDK from the official website, and then import it through the <script> tag

// Introduce ZegoWhiteboardView SDK
<script src="ZegoExpressWhiteboardWeb.js"></script>
// Introduce ZegoDocsView SDK
<script src="ZegoExpressDocs.js"></script>

Method 2: Use npm to obtain SDK

import { ZegoExpressEngine } from 'zego-express-whiteboard-web';
import { ZegoExpressDocs } from 'zego-express-docsview-web';
// or
const ZegoExpressEngine = require('zego-express-whiteboard-web').ZegoExpressEngine;
const ZegoExpressDocs = require('zego-express-docsview-web').ZegoExpressDocs;

3.1.2 Initialize ZegoWhiteboardView SDK

/**
 * Initialize ZegoWhiteboardView SDK
 * @param appID Is the application ID, please get it from the instant management ZEGO Admin Console- <a href="https://console-express.zego.im/">https:</a> //console-express.zego.im/
 * @param server To access the server address, please obtain it from the instant management ZEGO Admin Console- <a href="https://console-express.zego.im/">https:</a> //console-express.zego.im/
*/
const zegoExpressEngine = new ZegoExpressEngine(appID, server);

3.1.3 Initialize ZegoDocsView SDK

/**
* Initialize ZegoExpressDocs SDK
* @param appID Is the application ID, please get it from the instant management ZEGO Admin Console- <a href="https://console-express.zego.im/">https:</a> //console-express.zego.im/
* @param token The login verification token is obtained by registering the project in the instant ZEGO Admin Console, plus the specified algorithm; the test phase can be bypassed through the instant interface, and the user must implement it in the formal environment.
* @param userID User ID, a string of up to 64 bytes. Only supports numbers, English characters and'~','!','@','#', '
*/
const zegoExpressDocs = new ZegoExpressDocs({appID, token, userID});

3.2 Log in Room

Call the loginRoom interface and pass in the room ID parameters "roomID" and "token" and the user parameter "user" to log in to the room. Only by logging in to the room can all members in the room communicate with each other.

/**
* Login room
* @param roomID Room ID, a string with a maximum length of 128 bytes. Only supports numbers, English characters and'~','!','@','#', '

3.3 Create and Display ZegoDocsView and ZegoWhiteboardView

The creation and display of ZegoWhiteboardView must be completed after ZegoDocsView is displayed.

3.3.1 Callback when the Registration File is Loaded

Only when the callback is triggered does it mean that the file on ZegoDocsView has been loaded, that is, ZegoDocsView has been displayed.

/**
* Register the callback of file loading completion on ZegoDocsView
* @param Callback method
*/
zegoExpressDocs.on('onLoadFile', (res) => {
      // step1: At this point, ZegoDocsView has been displayed

      // step2: Call the loadFileCallback method defined in 3.4 below to create and display ZegoWhiteboardView
        loadFileCallback(res)
})

3.3.2 Create ZegoDocsView

A ZegoDocsView is created, and there is no file content on ZegoDocsView at this time.

<!--Html In a container div-->
<div id="parent"></div>

/**
* Create ZegoDocsView
* @param parent The ID of the parent container that needs to be mounted, the parent container positioning method must be relative positioning and the physical size is not 0
*/
const zegoDocsView = zegoExpressDocs.createView(parent);

3.3.3 Show ZegoDocsView

Load the specified file on ZegoDocsView.

/**
* Load the specified file on ZegoDocsView, the completion of loading will trigger the callback of the registered file above
* @param fileID The unique identification ID of the file, which will be returned after the source file is successfully transcoded
* @param authKey The business service and the ZegoDocs service agree on the shared authentication key generated by the algorithm. If the authentication fails, loadFile will fail. If authentication is not turned on, the key can be empty
*/
zegoDocsView.loadFile(fileID, '');

3.3.4 Create and Display ZegoWhiteboardView

Start to create and display ZegoWhiteboardView after the display of ZegoDocsView is complete.

// Create and display ZegoWhiteboardView, where the parameter res is the file-related information returned after the file is loaded
async function loadFileCallback(res) {
      // Create ZegoWhiteboardView based on file-related information
        const zegoWhiteboardView = await zegoExpressEngine.createView({
              roomID: roomID, // Current room ID
          name: res.fileName,
          aspectWidth: res.width,
          aspectHeight: res.height,
          pageCount: res.pageCount,
          fileInfo: {
                  fileID: res.fileID,
              fileName: res.fileName,
              fileType: res.fileType,
              authKey: res.authKey
          }
    });
         // Show ZegoWhiteboardView
      await zegoExpressEngine.attachView(zegoWhiteboardView, res.viewID);
}

3.4 Synchronous Scrolling and Page Turning Between ZegoDocsView and ZegoWhiteboardView

Whether it is page turning or scrolling is achieved through the scroll interface of ZegoWhiteboardView, the ZegoWhiteboardView SDK will automatically scroll or page the ZegoDocsView to the same position and synchronize it to other rooms people.

// Next page
function nextPage() {
      // step1: Get the current number of pages, the current total number of pages
    const currentPage = zegoWhiteboardView.getCurrentPage();
    const totalPage = zegoWhiteboardView.getPageCount();
      // step2: Check whether the current page can be turned
    if (currentPage >= totalPage || totalPage <= 1) return;
      // step3: Get the current scrolling direction, the file whiteboard is always portrait by default and cannot be modified
      const { direction } = zegoWhiteboardView.getCurrentScrollPercent();
      // step4: Calculate the percentage of the target page
    const percent = currentPage / totalPage;
    // step5: Determine the scrolling direction, perform scrolling or page turning
    if (direction === 1) {
        // Scroll horizontally
        zegoWhiteboardView.scroll(percent, 0);
    } else {
          // Vertical scroll
        zegoWhiteboardView.scroll(0, percent);
    }
}
// Previous page
function previousPage() {
      // step1: Get the current number of pages, the current total number of pages
    const currentPage = zegoWhiteboardView.getCurrentPage();
    const totalPage = zegoWhiteboardView.getPageCount();
      // step2: Check whether the current page can be turned
    if (currentPage <= 1 || totalPage <= 1) return;
      // step3: Get the current scrolling direction, the file whiteboard is always portrait by default and cannot be modified
      const { direction } = zegoWhiteboardView.getCurrentScrollPercent();
      // step4: Calculate the percentage of the target page
    const percent = (currentPage - 2) / totalPage;
      // step5: Determine the scrolling direction, perform scrolling or page turning
    if (direction === 1) {
          // Scroll horizontally
        zegoWhiteboardView.scroll(percent, 0);
    } else {
          // Vertical scroll
        zegoWhiteboardView.scroll(0, percent);
    }
}

3.5 Destroy the Document Whiteboard

Call destroyView to destroy the document whiteboard.

/**
* Destroy the specified file whiteboard, ZegoWhiteboardView SDK will automatically destroy ZegoWhiteboardView and the corresponding ZegoDocsView related resources
* @params ZegoWhiteboardView
*/
zegoExpressEngine.destroyView(zegoWhiteboardView);

4 Sample Code

The above introduces the basic scenarios of Collaborative Whiteboard and File Sharing. For more complex interactive scenarios, please view the complete sample source code. For details, please refer to Sample Codes.