Documentation
File Sharing
Advanced Features
H5 File Production and Use

H5 File Production and Use

Last updated：2022-03-22 13:07

1 Introduction

1.1 Introduction

H5 files refer to HTML5 pages created by developers for multi-terminal sharing, and are a new file type supported by ZegoDocsView SDK. Developers can add functions such as page turning, skipping, animation triggers, audio and video in H5 files similar to dynamic PPT.

1.2 Concept Explanation

ZEGO Bridge Layer: A bridge for the interaction between H5 files and ZegoDocsView SDK. Only when the ZEGO bridge layer is introduced in H5 files can it communicate with ZegoDocsView SDK to achieve multi-terminal intercommunication.
ZEGOBridge: The ZEGO bridge layer injects an object in the global. After the H5 file introduces the bridge layer, this object can be read, and the only instance of ZEGOBridge can be obtained through this object.
Bridge: The only instance of ZEGOBridge. This instance contains all the methods that H5 files need to use.
Operation record: All operations performed in the H5 file except for page turning and skipping are called an operation record, which is bound to the page, that is, the operation record under a certain page.
Operation record list: a collection of all operation records on a page. When the number of pages is changed, the list will be automatically cleared internally. All actions of the H5 file except page turning and skipping rely on this list to execute.

1.3 Document Description

This article will introduce two parts through the production and use of H5 files:

H5 file production: from integrating the ZEGO bridge layer to interacting with the ZEGO bridge layer.
Use of H5 files: upload from ZegoDocsView SDK to subsequent multi-terminal intercommunication.

2 Sample Codes

ZEGO provides the completed H5 file for developers' reference, including the integrated ZEGO bridge layer and how to use the interface. For details, please refer to H5 file sample source code.
Please refer to Sample Codes for the complete sample source code of using H5 files in ZegoDocsView SDK.

3 Interactive Timing Diagram

This sequence diagram describes the interaction process of the H5 file through the ZEGO bridge layer and ZegoDocsView SDK when the developer makes the H5 file.

4 Production Steps

The production of H5 files, that is, how to integrate and interact with the ZEGO bridge layer, is divided into the following 5 steps. Developers please make sure to follow the steps below.

4.1 Introduce the ZEGO Bridge Layer

Introduce the ZEGO bridge layer in the H5 file. Developers need to ensure that the H5 resource has been loaded when using the bridge layer method.

ZEGOBridge is a singleton mode. Only one Bridge instance can exist in a page. Only when the bridge layer is introduced can the related methods be used.

The bridge layer file address is as follows:

https://storage.zego.im/ppt2h5/ZEGOBridge.js

Introduce code examples:

<script src="https://storage.zego.im/ppt2h5/ZEGOBridge.js"></script>

4.2 Register Callback

Call getInstance to register related callbacks and get the only instance of the bridge layer.

In order to achieve the effect of multi-terminal interoperability, all business operations that need to be executed in the H5 file must first call the bridge layer interface, and then execute in the corresponding callback.

// Get the unique instance
const bridge = ZEGOBridge.getInstance({
    // Register page flip, skip callback
    onPageChange: function (params) {
        // A Promise object needs to be returned in this callback function to notify the bridge layer that the current page turning and skipping tasks have been completed
        return new Promise(resolve => {
            // Execute specific page turning and stepping logic
            // Specific business logic
            resolve();
        });
    },
    // Register operation record callback
    onRecordChange: function (params)
    {
        // Need to return a Promise object in this callback function to notify the bridge layer that the current operation task has been executed
        return new Promise(resolve => {
            // recordList represents the current operation record list
            // oldRecordList last operation record list
            // recordType generates the operation type of the current operation record list, and can implement specific services according to this type
            const {recordList, oldRecordList, recordType} = params;
            // Execute specific business logic according to recordType, recordList, oldRecordList
            resolve();
        });
    },
    // Register error callback, optional
    onError: function (params) {
        // Specific business logic
    }
});

4.3 Incoming Page Initial Information

Call getReady to notify the bridge layer that the page is ready, and pass in information such as the initial page number, step number, total page number, and current page total step number.

Other interfaces must be called after getReady is called to take effect.

// Pass in the initial number of pages, the number of steps, the total number of pages, all pages correspond to the total number of steps
bridge.getReady({
    page: 1, // The initial page number is 1
    step: 1, // The initial number of steps on the current page is 1
    pageCount: 3, // The total number of pages is 3
    maxSteps: [5, 3, 1] // There are 3 pages in total, and the total number of steps on each page is 5, 3, 1 respectively
})

4.4 Page Turn/Skip

Call requestChangePage to notify the bridge layer that it needs to turn pages and skip steps.

This is just to send page turning and step requests, which does not mean that the request is successful. Please perform specific operations in the registered onPageChange callback.

// Request to jump to page 3, step 1
bridge.requestChangePage(3, 1);

4.5 Other Operations

Call other related interfaces to notify the bridge layer that other operations are currently required to be performed.

The operation request is only sent here, and it does not mean that the request is successful. Please perform the specific operation in the registered onRecordChange callback. All updates to the operation record list will be reflected in the onRecordChange callback parameter.

// At this time, add a record with the current page content as id
bridge.pushRecord({ id:'ZEGO' })

// Remove the last operation record
bridge.popRecord()

// Clear the operation record of the current page
bridge.clearRecordStack()

// Replace all operation records on the current page with the record whose content is name
bridge.replaceRecordStack({ name:'ZEGO' })

5 Use Steps

After the H5 file is successfully created, if you want to achieve multi-terminal interoperability, please follow the steps below:

Please refer to File Sharing - Integration to integrate ZegoDocsView SDK in the project to realize basic file sharing services.
Please refer to File Sharing - Implementation Process to upload and render H5 files.
Please refer to Collaborative Whiteboard - Integration, Collaborative Whiteboard - Implementation Process for multi-terminal synchronization.

6 Document Production and Usage Specifications

Please refer to H5 Document Specification for H5 document production and usage specifications.

7 H5 Bridge Layer API

The following introduces the H5 bridge layer API.

7.1 Get the Only Instance of the Bridge Layer

// Callback parameters for changing the number of steps and pages
interface OnPageChangeParams {
    page: number; // current page number, starting from 1
    step: number; // current step number, starting from 1
    oldPage: number; // Original page number, starting from 1
    oldStep: number; // original step number, starting from 1
    taskID: string; // task ID
}

// Operation record type
enum RecordType {
    Push = 1, // append, corresponding to pushRecord interface
    Pop, // remove the latest one, corresponding to the popRecord interface
    Replace, // Full replacement, corresponding to the replaceRecordStack interface
    Clear, // Clear, corresponding to the clearRecordStack interface
    Stop = 100, // Stop audio and video scene
    LateJoinRoom = 101, // Back-in room scene
    Back = 102 // The operation failed back to the scene
}

// Operation record list change callback parameters
interface OnRecordChangeParams {
    recordList?: any[]; // current operation list, does not exist when recordType = 100
    oldRecordList?: any[]; // Original operation list, does not exist when recordType = 100
    taskID: string; // task ID
    recordType: RecordType; // Operation record type
    push: boolean; // Is the current operation a remote push
}

// Failed callback parameters
interface OnErrorParams {
    code: number; // error code
    msg: string; // error description
    data?: any; // Business parameters
    error?: Error; // Error stack
}

// Callback for changes in steps and pages
type pageChangeCallback = (params: OnPageChangeParams) => Promise<any>;

// Operation record change callback
type recordChangeCallback = (params: OnRecordChangeParams) => Promise<any>;

// Error callback
type errorCallback = (params: OnErrorParams) => void;

// Get the parameters that need to be passed in for the instance
interface BridgeOptions {
    onPageChange: pageChangeCallback; // Page number, step number change callback
    onRecordChange: recordChangeCallback; // record change callback
    onError?: errorCallback; // Error callback, optional
}

// Get ZEGOBridge singleton
static getInstance(options: BridgeOptions): Bridge;

7.2 Notify the Bridge Layer File is Ready

// page initial data
interface InitData {
    page: number; // The initial page number of the file, starting from 1
    step: number; // The step number of the initial current page of the file, starting from 1
    pageCount: number; // The total number of pages of the file
    maxSteps: number[]; //The total number of steps corresponding to all pages of the file.

}

/**
 * Notify the bridge layer page is ready
 *
 * Timing of calling: When the script is successfully introduced, the page is ready, and multi-terminal synchronization is possible
 *
 * note: Generally, it can be called in the event callback of page load
 *
 * @param data page initial data
 */
getReady(data: InitData): void

7.3 Request Page Turning/Skip

/**
 * Send page turning, skip request
 *
 * Timing of calling: when the page is ready, after the call to getReady is completed, when you need to turn pages or skip steps
 *
 * note: This is just to send page turning and skipping requests, which does not mean that the request is successful. Please perform specific operations in the onPageChange callback
 *
 * @param page target page number
 *
 * @param step target number of steps, optional, if not filled, the default is 1, which means to jump to the first step of the current page
 *
 * @return Request task ID, unique identification
 */
requestChangePage(page: number, step?: number): string

7.4 Request Other Operations

ZEGOBridge provides 4 interfaces to combine page operations. All interfaces are used to update the operation record list recordList of the current page. H5 files need to ensure that the recordList cannot exceed the maximum length limit of the ZEGO bridge layer after the combined call. If the limit is exceeded, the bridge layer will Thrown in the onError callback, the current operation request will be invalid.

Maximum length calculation rule: The number of bytes after the recordList is converted to base64 cannot exceed 948 bytes.

7.4.1 Append an Operation Record of the Current Page

/**
 * Add an operation record
 *
 * Timing of the call: when the page is ready, after the call to getReady is complete, when additional operations are needed
 *
 * note: This is just to send the request, it does not mean that the request is successful, please perform the specific operation in the onRecordChange callback
 *
 * note: If the developer needs to pay attention to the operation history, please use this method
 *
 * @param record operation record
 *
 * @return Request task ID, unique identification
 */
pushRecord(record: string | number | Array<any> | object | boolean | null): string

7.4.2 Remove the Last Operation Record

/**
 * Remove the last operation record
 *
 * Timing of the call: the page is ready, after the getReady call is completed, when the last operation record needs to be removed
 *
 * note: This is just to send the request, it does not mean that the request is successful, please perform the specific operation in the onRecordChange callback
 *
 * @return Request task ID, unique identifier and the most recent operation record
 */
popRecord(): {taskID: string; record: string | number | Array<any> | object | boolean | null}

7.4.3 Clear the Operation Record of the Current Page

/**
 * Clear the operation record of the current page
 *
 * Timing of calling: the page is ready, after the call to getReady is completed, when the current page operation record needs to be cleared
 *
 * note: This is just to send the request, it does not mean that the request is successful, please perform the specific operation in the onRecordChange callback
 *
 * note: Whenever the number of pages is changed, the script has cleared the operation record. Under normal circumstances, the developer does not need to use this method
 *
 * @param record operation record
 *
 * @return Request task ID, unique identification
 */
clearRecordStack(): string

7.4.4 Replace the Operation Record List of the Current Page in Full

/**
 * Replace the current page operation record
 *
 * Timing of calling: the page is ready, after the call to getReady is completed, when the current page operation record needs to be replaced
 *
 * note: This is just to send the request, it does not mean that the request is successful, please perform the specific operation in the onRecordChange callback
 *
 * note: replace the current operation record list in full, if the developer does not need to pay attention to the operation history record, please use this method
 *
 * @param record operation record
 *
 * @return Request task ID, unique identification
 */
replaceRecordStack(record: string | number | Array<any> | object | boolean | null): string

8 H5 Bridge Layer Error Code

For H5 bridge layer error codes, please refer to Common Error Codes.