Quick Start: WebOffice Online Document Collaboration

Supported file formats

The following file formats are supported for preview and editing. For a complete list of document format limits, see Document limits.

Token lifecycle

JS-SDK automatically calls RefreshWebofficeToken 5 minutes before the token expires. Set the timeout value to greater than 20 minutes (20 x 60 x 1000 milliseconds) to prevent frequent token refreshing. The default token validity period is 30 minutes.

Call GenerateWebofficeToken to obtain the collaboration URL

Request example

{
    "ProjectName": "test-project",        // The name of the IMM project.
    "SourceURI": "oss://test-bucket/test-object.docx", // The URI of the document in OSS.
    "Filename": "test-object.docx",       // The name of the document.
    "UserData": "{\"fid\": \"123\"}",     // The user data, which is returned in the MNS notification.
    "PreviewPages": 3,                    // The number of preview pages.
    "Permission": "{\"Rename\": \"true\", \"Readonly\": \"false\"}", // The permissions.
    "User": "{\"Id\": \"test\", \"Name\": \"testuser\", \"Avatar\": \"http://xx.com/avatar.jpg\"}", // The user information displayed for online collaboration.
    "Watermark": "{\"Type\": \"1\", \"Value\": \"imm\"}" // Set a watermark.
}

Response example

{
    "RefreshToken": "f1fd1afd79ee445f95d3dd99f34f35ffv3",
    "RequestId": "BC63D209-5E53-00E9-8D24-7043943DBC89",
    "AccessToken": "3de242da81e1433abefbbea000aaae39v3",
    "RefreshTokenExpiredTime": "2022-07-06T23:18:52.856132358Z",
    "WebofficeURL": "https://office-cn-shanghai.imm.aliyuncs.com/office/w/7c1a7b53d6a4002751ac4bbaea69405a01475f4a?_w_tokentype=1",
    "AccessTokenExpiredTime": "2022-07-05T23:48:52.856132358Z"
}

Complete sample code (IMM SDK for Python V1.27.3)

# -*- coding: utf-8 -*-
import os
from alibabacloud_imm20200930.client import Client as imm20200930Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_imm20200930 import models as imm_20200930_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client(
        access_key_id: str,
        access_key_secret: str,
    ) -> imm20200930Client:
        """
        Use the AccessKey ID and AccessKey secret to initialize a client.
        @param access_key_id:
        @param access_key_secret:
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config(
            access_key_id=access_key_id,
            access_key_secret=access_key_secret
        )
        # Specify the domain name you want to access.
        config.endpoint = f'imm.cn-shenzhen.aliyuncs.com'
        return imm20200930Client(config)

    @staticmethod
    def main() -> None:
        # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M.
        # We recommend that you do not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code for data security reasons.
        # In this example, the AccessKey pair is read from the environment variables to implement identity verification for API access. For information about how to configure environment variables, visit https://www.alibabacloud.com/help/en/imm/developer-reference/configure-environment-variables?spm=a3c0i.29367734.6737026690.8.6d266e9bORGXvg.
        imm_access_key_id = os.getenv("AccessKeyId")
        imm_access_key_secret = os.getenv("AccessKeySecret")
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        # Set a watermark.
        weboffice_watermark = imm_20200930_models.WebofficeWatermark(
            type=1,
            value='imm'
        )
        # Set the collaborator information.
        weboffice_user = imm_20200930_models.WebofficeUser(
            id='test',
            name='testuser',
            avatar='http://xx.com/avatar.jpg'
        )
        # Set permissions.
        weboffice_permission = imm_20200930_models.WebofficePermission(
            rename=True
        )
        get_weboffice_urlrequest = imm_20200930_models.GenerateWebofficeTokenRequest(
            # Set the IMM project name.
            project_name='test-project',
            # Set the URI of the document for collaboration.
            source_uri='oss://test-bucket/test-object.docx',
            # Set the name of the document.
            filename='test-object.docx',
            # Set user data.
            user_data='{"fid": "123"}',
            preview_pages=3,
            external_uploaded=False,
            permission=weboffice_permission,
            user=weboffice_user,
            watermark=weboffice_watermark
        )
        runtime = util_models.RuntimeOptions()
        try:
            # Print the return value of the API operation.
            response = client.get_weboffice_urlwith_options(get_weboffice_urlrequest, runtime)
            print(response.body.to_map())
        except Exception as error:
            # Print the error message if necessary.
            UtilClient.assert_as_string(error.message)
            print(error)


if __name__ == '__main__':
    Sample.main()

Call RefreshWebofficeToken to refresh the AccessToken

When an AccessToken expires, the frontend calls the RefreshWebofficeToken operation on the server to obtain a new one. The response format matches the GenerateWebofficeToken response.

Import JS-SDK

In the following example, ${x.y.z} is a placeholder for the JS-SDK version number. Replace it with the actual latest version. For version information, see JS-SDK versions.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Demo</title>
</head>
<body>
  <script src="https://g.alicdn.com/IMM/office-js/${x.y.z}/aliyun-web-office-sdk.min.js"></script>
  <script>
    console.log('After importing, the JS-SDK is available for use!');
    console.log(aliyun); //Global variable name.
  </script>
</body>
</html>

Initialize the JS-SDK

The frontend obtains the tokenInfo object by calling the GenerateWebofficeToken operation on your server.

The following example assumes the tokenInfo object matches the GenerateWebofficeToken response structure. The server endpoint /getTokenInfo represents your server-side GenerateWebofficeToken wrapper.

// Obtain the collaboration URL and AccessToken.
var tokenInfo = await $.get('http://example.com/getTokenInfo')

// Initialization
let instance = aliyun.config({
  url: tokenInfo.WebofficeURL // Set the document collaboration URL.
})

Set the iframe mount point

By default, the iframe is mounted to the body element. To specify a custom mount point:

let instance = aliyun.config({
  mount: document.querySelector('#container'),
  url: 'The document collaboration URL' // The document collaboration URL tokenInfo.WebofficeURL from Step 2b.
})

To customize the iframe object, access the DOM object through the JS-SDK instance:

var instance = aliyun.config({
    mount: document.querySelector('#container')
   //...
})
console.log(instance.iframe)

Set the token

Set the token to access the collaboration URL. You must call this method again each time the token is refreshed.

// Obtain the token by using an asynchronous request or template output based on your business requirements.
var token = 'yourToken';
// Specify the token.
instance.setToken({
  token: token,
  timeout: 25 * 60 * 1000, // The token validity period. This parameter is required. Unit: milliseconds. In this example, the token validity period is set to 25 minutes. You can use the refreshToken function to refresh the token 5 minutes before it expires.
})

Set up automatic token refresh

The frontend obtains the tokenInfo object by calling the RefreshWebofficeToken operation on your server. The following example assumes the tokenInfo object matches the RefreshWebofficeToken response structure.

Pass in a function that obtains the token. When the token validity period expires, JS-SDK automatically calls this function. The function must return a promise or a plain object containing the new token.

The following example uses the server endpoint /refreshTokenInfo to represent your server-side RefreshWebofficeToken wrapper.

// Cache the last tokenInfo for token refreshing.
  let lastTokenInfo = tokenInfo

// Obtain the token function.
// Note: refreshToken does not support async functions. Only promise or {token,timeout} objects can be returned.
  const refreshToken = function() {
    return new Promise(function(resolve){
      // The business processing logic. Call the refreshToken operation that is encapsulated on the server.
      $.get('http://example.com/refreshTokenInfo',{
        RefreshToken: lastTokenInfo.RefreshToken,
        AccessToken: lastTokenInfo.AccessToken,
        //....
      }).then(function(tokenInfo){
        lastTokenInfo = tokenInfo
        resolve({
          token: tokenInfo.AccessToken, // This parameter is required.
          timeout: 25 * 60 * 1000, // The token validity period. This parameter is required. Unit: milliseconds. In this example, the token validity period is set to 25 minutes. You can use the refreshToken function to refresh the token 5 minutes before it expires.
        })
      })
    })
  }
// Configure the function that obtains the token.
aliyun.config({
  //...
  refreshToken
})