Documentation
File Sharing
Quick Starts
Implementation

Implementation

Last updated：2022-03-22 13:07

ZEGOCLOUD no longer classifies environments into production environments and testing environments.

If you create your project in ZEGOCLOUD Admin Console on/before 2021-11-16, refer to the Testing environment deprecation to upgrade the SDK and adjust related codes.

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

Create a project in the ZEGO Admin Console and apply for a valid AppID and AppSign. For details, please refer to the Console - Project Management.
Integrate ZegoDocsView SDK into the project. For details, please refer to Quick Starts- Integration.

By default, the features of this product are not enabled. To use these features, you will need to contact ZEGOCLOUD Technical Support to enable them first.
For SDK version 2.3.0 or later, you can also use Tokens for authentication. To upgrade the authentication mode, refer to the Upgrade the authentication mode from AppSign to Token.

3 Implementation Steps

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

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

If you want to realize the function of drawing on files and multi-terminal linkage, you need to introduce the Collaborative Whiteboard function. For details, please refer to ZegoWhiteboardView SDK.

3.1 Initialize SDK

3.1.1 Introducing Header Files

// Introduce ZegoDocsView SDK header files
#import <ZegoDocsView/ZegoDocsView.h>

3.1.2 Initialize ZegoDocsView SDK

When initializing the SDK, you need to set the log file save path, the SDK internal data file save path, the file cache path, and the operating environment.

The operating environment parameters need to be consistent with the corresponding environment when applying for AppID.

ZegoDocsViewConfig *config = [ZegoDocsViewConfig new];
config.appSign = appSign; //That is, AppSign
config.appID = appID;//that is, AppID
config.dataFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"data"];//SDK Related data catalog
config.cacheFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"doc"];//SDK Related cache directory
config.logFolder = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents/ZegoDocs"] stringByAppendingString:@"log"];//SDK Related log directory

[[ZegoDocsViewManager sharedInstance] initWithConfig:config completionBlock:^(ZegoDocsViewError errorCode) {
    if (errorCode == ZegoDocsViewSuccess) {
        NSLog(@"Successfully initialized SDK");
    } else {
        NSLog(@"Failed to initialize SDK %ld",errorCode);
    }
}];

3.2 Upload Files

Call the upload file method of ZegoDocsViewManager to upload the file to the ZEGO file cloud service. After the upload is successful, the fileID of the file will be obtained, and the developer can call ZegoDocsView LoadFileWithFileID interface, input fileID to load the file.

The uploaded file must meet the corresponding specifications:

Please use Microsoft Office 2013 or above to edit/save the file. Files saved in earlier versions of Microsoft Office or other office software, such as WPS, Keynote, Microsoft Office 2003, etc., are not supported.
The file must be editable and does not support "read-only", "encrypted", or other protected documents, otherwise the transcoding will fail.

For all specifications, please refer to Overview - File Specification.

File upload is divided into two stages: upload ZegoDocsViewUploadStateUpload and format conversion ZegoDocsViewUploadStateConvert.

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 "infoDictionary" is {"upload_percent":@(0.50)}; if the current upload is 100%, the content of "infoDictionary" is {"upload_percent":@(1.00)}.
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 "infoDictionary" is {"upload_fileid":"ekxxxxxxxxv"}. The corresponding value of upload_fileid is the file fileID.

3.2.1 Upload Common Files

Call the uploadFile method to upload ordinary files.

//filePath The absolute path of the file to be uploaded can be obtained using the iOS system API.
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"pdf"];

//The rendering mode type after uploading the file after transcoding, the default is ZegoDocsViewRenderTypeVector format, if the user is involved in the business of iOS, Web, Windows, Mac, and applets, it is recommended to use ZegoDocsViewRenderTypeVectorAndIMG mode.
ZegoDocsViewRenderType renderType = ZegoDocsViewRenderTypeVectorAndIMG;

[[ZegoDocsViewManager sharedInstance] uploadFile:filePath renderType:renderType completionBlock:^(ZegoDocsViewUploadState state, ZegoDocsViewError errorCode, NSDictionary * _Nonnull infoDictionary) {
  if (errorCode == ZegoDocsViewSuccess) {
    if (state == ZegoDocsViewUploadStateUpload) {
      // uploading...
      NSString *uploadPercent = infoDictionary[@"upload_percent"];
      if(uploadPercent.intValue == 1){
        // Transcoding...
      }
    } else if (state == ZegoDocsViewUploadStateConvert){
      // The conversion is successful, the file ID is obtained, and the fileID can be obtained through the "upload_fileid" key
      // You can call ZegoDocsView's loadFile interface and pass in the fileID to load the file.
      NSString *fileID = infoDictionary[@"upload_fileid"];

      /* Uploaded successfully
          [self.zegoDocsView loadFileWithFileID:fileID authKey:nil completionBlock:^(ZegoDocsViewError errorCode) {
            NSLog(@"%d", errorCode);
             }];
             */
    }
  } else {
    // upload failed
  }
}];

3.2.2 Upload H5 Files

Set the configuration parameters of uploading H5 files through ZegoDocsViewCustomH5Config, and call the uploadH5File method to upload H5 files.

//The absolute path of the file, which can be obtained according to the iOS API
    [[ZegoDocsViewManager sharedInstance] uploadH5File:[url path] config:config completionBlock:^(ZegoDocsViewUploadState state, ZegoDocsViewError errorCode, NSDictionary * _Nonnull infoDictionary) {
    if (errorCode == ZegoDocsViewSuccess) {
            if (state == ZegoDocsViewUploadStateUpload) {
                // uploading...
                if(upload_percent.intValue == 1){
                    // Transcoding...
                }
            } else if (state == ZegoDocsViewUploadStateConvert){
                // Successful conversion
            }
        } else {
            // upload failed
        }
    }];

3.3 Load Files

3.3.1 Create ZegoDocsView

Create ZegoDocsView and add it to the view.

// 1. init
self.docView = [[ZegoDocsView alloc] init]; //Initialization file View
self.docView.backgroundColor = UIColor.whiteColor; //Set the background color of the file View
[self.docView setDelegate:self]; //Set file View proxy notification
[self.view addSubview:self.docView]; //Add to the View you need to display
// 2. Set the frame
self.docView.frame = CGRectMake(0, 0, 100, 100);

3.3.2 Load and Render Files

Call the loadFileWithFileID interface of ZegoDocsView, and pass in the fileID load file obtained after the upload is successful.

// fileID Get after uploadFile succeeds
NSString *fileID = @"";
[self.docView loadFileWithFileID:fileID //Get the file ID in the background
 authKey:@"" //Authentication key. Can be empty. Fill in according to whether the environment you are applying for requires authentication. It is best to get it through the background
 completionBlock:^(ZegoDocsViewError errorCode) {

}];

If you encounter loading failure, please refer to Error Codes. The common reasons are as follows:

The AppID applied by the developer does not include the ability to File Sharing , so you need to apply to ZEGO technical support for activation.
Upload files and load files use different AppIDs. For example, if the developer uploads File 1 in AppID1, but loads the fileID of File 1 in AppID2, the file cannot be found at this time.
The file upload and loading environment are inconsistent. For example, if a file is uploaded in a formal environment but loaded in a test environment, the file will not be found at this time.

After the current DocsView has called the loadFileWithFileID interface to load the file, you need to call the unloadFile interface to unload the file before you can use the loadFileWithFileID to load the file again.
The loadFileWithFileID interface can only be called before, and then the reloadFileWithCompletionBlock interface can be called.

3.4 Use the Basic Functions of ZegoDocsView

3.4.1 Page Turning

After the file is loaded successfully, you can call the flipPage method of ZegoDocsView to turn the pages of the file.
After the file is loaded successfully, ZegoDocsView can be scrolled/paged by default by touching it.

There are two methods for turning pages for dynamic PPT and non-dynamic PPT.
Both the jump page and current page steps start with 1.

// Example: Non-dynamic PPT Jump to page 3.
[self.docView flipPage:3 completionBlock:^(BOOL isScrollSuccess) {
            NSLog(@"End of page turning");
        }];

// Example: Dynamic PPT Jump to page 2, step 4.
[self.docView flipPage:2 step:4 completionBlock:^(BOOL isScrollSuccess) {
            NSLog(@"End of page turning");
        }];

3.4.2 File Zoom

After the file is loaded successfully, you can call scaleDocsViewWithScaleFactor to zoom 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.

[self.docsView scaleDocsViewWithScaleFactor:scaleFactor scaleOffsetX:scaleOffsetX scaleOffsetY:scaleOffsetY];

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 supports four file formats: PDF, PPT, dynamic PPT and H5 file.
It needs to be called after the file is loaded successfully.

NSArray *thumbnailUrls = [self.docsView getThumbnailUrlList];

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.

 [self.docView switchSheet:0];

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 nextStepWithCompletionBlock and previousStepWithCompletionBlock methods to perform the previous and next steps of the dynamic PPT, and perform the dynamic PPT jump up and down turn. The operation of dynamic PPT can only be called after the file is loaded.

//Previous
[self.docViewFirst previousStepWithCompletionBlock:^(BOOL isScrollSuccess) {

}];
//Next
[self.docViewFirst nextStepWithCompletionBlock:^(BOOL isScrollSuccess) {

}];

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.