Implementation

---

1 Concept Explanation

• ZEGO File Cloud Service: Refers to the server where ZEGO stores files. Developers upload files to this server.
• ZegoDocsView SDK: the client SDK corresponding to the File Sharing service.
• ZegoDocsView: file view, developers can use this view to load and display files on the ZEGO file cloud service.

2 Prerequisites

1. Create a project in the ZEGO Console and apply for a valid AppID and AppSign. For details, please refer to the Console - Project Management.

2. Integrate ZegoDocsView SDK into the project. For details, please refer to Quick Starts - Integration.

3 Implementation Steps

This section is divided into four parts to introduce the ZegoDocsView SDK:

1. Initialize the SDK
2. Upload files: upload local files to the ZEGO file cloud service
3. Load file: Load the file on the ZEGO file cloud service through the file ID and display it
4. Use the basic functions of ZegoDocsView

3.1 Initialize SDK

To initialize the SDK, you need a Token to verify your identity. For how to obtain it, please refer to Implementation - Log in to a room of Real-time Audio and Video.

Method 1: Download the SDK from the official website, and manually integrate the initialization of the SDK.

<script src="ZegoExpressDocs.js"></script>

/**
* Initialize ZegoExpressDocs SDK
* @param appID: ZEGO The application ID issued to the developer, please apply from the ZEGO management ZEGO Admin Console
* @param token: token
* @param userID: userID
*/
const zegoExpressDocs = new window.ZegoExpressDocs({appID, token, userID});

Method 2: Use npm to get the SDK initialization.

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

/**
* Initialize ZegoExpressDocs SDK
* @param appID: ZEGO The application ID issued to the developer, please apply from the ZEGO management ZEGO Admin Console
* @param token: token
* @param userID: userID
*/
const zegoExpressDocs = new ZegoExpressDocs({appID, token, userID});

3.2 Upload Files

Call the method of uploading files in ZegoExpressDocs to upload the file to the ZEGO file cloud service. After the upload is successful, the fileID of the file can be obtained from the parameters returned, and the developer can call ZegoDocsView loadFile interface, input fileID to load the file.

There are multiple stages in the file upload process, and developers need to pay special attention to the following two stages:

• Uploading stage: If it is uploaded normally, there will be multiple callbacks, each time including the file upload progress. For example, if the current upload is 50%, the content of "data" is {"uploadPercent":50}; if the current upload is 100%, the content of "data" is {"uploadPercent":100}.
• Format conversion stage: If the conversion is successful, only one callback will be generated, including the converted file ID. For example, the current conversion is completed, the content of "data" is {"fileID":"ekxxxxxxxxv"}. The corresponding value of fileID is the file fileID.

For other upload stages, please refer to ZegoDocsViewUploadModel.

3.2.1 Upload Common Files

Call the uploadFile interface to upload ordinary files.

//The rendering mode type after uploading the file after transcoding. If the user is involved in the business of iOS, Web, Windows, Mac, and applets, it is recommended to use the ZegoDocsViewRenderTypeVectorAndIMG mode.
//After uploading the file successfully, the file ID will be returned

zegoExpressDocs.uploadFile(file, renderType):Promise<any>

It is recommended to pay attention to the following events:

//When uploading a file, you will receive a callback for uploading the file uploadFile
zegoExpressDocs.on('onUpload', function(data: ZegoDocsViewUploadModel){
 ...
})

3.2.2 Upload H5 Files

Call uploadH5File to upload H5 file.

/***
*@param myFile: upload files
*@param config: H5 courseware related configuration information
*@param listener: Callback of upload progress
*/
zegoExpressDocs.uploadH5File(myFile, config, function (res) {
  console.log('uploadH5File', res);
}).then(function (res) {
  console.log('uploadH5FileID', res);
});

3.3 Load Files

3.3.1 Create ZegoDocsView

Call createView to create a file view.

/**
* Create docView
* @param parent: ZegoDocsView Mount container ID
* eg:<div id="parent"></div>
*/
const docView = zegoExpressDocs.createView(parent);

3.3.2 Add Files to the View

Call loadFile to add the file to the view.

// authKey Can be an empty string
docView.loadFile(fileID, authKey)

It is recommended to pay attention to the following events:

// When uploading a file, you will receive the callback of uploading the file loadFile, and get the relevant information of the loaded target file
zegoExpressDocs.on('onLoadFile', function(data: ZegoDocsViewLoadFileModel){
 ...
})

3.4 Use the Basic Functions of ZegoDocsView

3.4.1 Page Turning

• After the file is loaded successfully, you can call the flipPage interface of ZegoDocsView to flip the file.
• After loading the file successfully, you can call the scrollTo interface of ZegoDocsView to scroll through the pages of the file.

/**
* Jump to the specified page position.
* @param page: Jump to the target page, starting from 1
* @param step: The step corresponding to the jump target page, starting from 1 (only for dynamic PPT)
*/
docView.flipPage(page: number, step?: number)

// Example: Non-dynamic PPT Jump to page 3.
docView.flipPage(3)

// Example: Dynamic PPT Jump to page 2, step 4.
docView.flipPage(2,4)

/**
* Jump to the vertical offset percentage.
* @param verticalPercent: Percentage of longitudinal offset, the parameter value range is 0.00 ~ 1.00, for example, if you want to jump to half of the position, the input parameter is 0.50
*/
docView.scrollTo(verticalPercent: number)

3.4.2 File Zoom

After the file is loaded successfully, you can call setScaleFactor to scale the file.

• scaleFactor: File scaling needs to specify a scaling factor, that is, the scale factor for reducing or enlarging.
• scaleOffset: The left starting point of the area to be displayed after zooming in or out.

/**
* Zoom
* @param scaleFactor: The zoom factor, a positive number not less than 1
* @param scaleOffsetX: X axis zoom offset
* @param scaleOffsetY: Y-axis zoom offset
* @note  Currently the offset is not yet supported, so you don’t need to pass it
*/
docView.setScaleFactor(scaleFactor: number, scaleOffsetX?: number, scaleOffsetY?: number)

/**
* Get zoom object
* @return {scaleFactor: Zoom multiple; scaleOffsetX: X-axis zoom offset; scaleOffsetY: Y-axis zoom offset}
*/
docView.getScaleFactor(): {scaleFactor: number; scaleOffsetX: number; scaleOffsetY: number}

3.4.3 Get File Thumbnail

After the file is loaded successfully, you can call getThumbnailUrlList to get the file thumbnail.

/**
* Get the current file thumbnail list, only support PDF, PPT, dynamic PPT, H5 file format, can be called after the file is loaded successfully
* @return File thumbnail URL array
*/
docView.getThumbnailUrlList(): Array<string>

3.4.4 Excel File Switching Sheet

If the file uploaded by the developer is an Excel file and there are multiple sheet pages, you can use the switchSheet method to switch the sheet pages, and the sheet pages start from 0.

docView.switchSheet(sheetIndex)

3.4.5 Dynamic PPT Operation

Dynamic PPT, that is, a file whose file type is "ZegoDocsViewFileTypeDynamicPPTH5", this type of file may have multiple steps per page.

If the file uploaded by the developer is a dynamic PPT file, you can use the nextStep and previousStep methods to perform the previous and next steps of the dynamic PPT, and jump up and down the dynamic PPT turn. The operation of dynamic PPT can only be called after the file is loaded.

/**
* Next, only for dynamic PPT ZegoDocsViewFileTypeDynamicPPTH5 type operations
*/
docView.nextStep()

/**
* In the previous step, only for dynamic PPT ZegoDocsViewFileTypeDynamicPPTH5 type operations
*/
docView.previousStep()

4 Sample Code

Developers can experience the File Sharing business in the File Sharing sample project, and view the complete source code and code logic. For details, please refer to File Sharing - Sample Codes.