tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

Custom Configuration Overview

Last updated: 2022-10-26 15:28:31

    Feature Description

    By using the JS-SDK, you can customize capabilities such as UI, page status, and event listener to deliver a better webpage experience.

    Architecture diagram

    Operating Environment

    Platform Supported Browsers
    iOS Safari, QQ built-in browser, QQ Mini Program, WeChat built-in browser, and WeChat Mini Program
    Android QQ built-in browser, QQ Mini Program, WeChat built-in browser, and WeChat Mini Program
    Windows Chrome, QQ Browser (non-compatibility mode), Edge, Firefox, and Internet Explorer 11
    macOS Chrome, Safari, QQ Browser, Edge, and Firefox

    Instructions

    1. Download

    Download the latest version of the JS-SDK package. For earlier versions, see Release Notes.

    2. Import the JS-SDK

    On the page that needs to call the JS-SDK, import it as follows. In the sample code, ${version} indicates the version number and should be replaced with the actual version number of your downloaded package.

    <script src="sdk-${version}.js"></script>

    3. Get the online file preview URL

    Option 1. Use the JS-SDK (on v0.1.1 or later) to get

    Use the JS-SDK (on v0.1.1 or later) to get the online file preview URL as follows:

    var url = await COSDocPreviewSDK.getPreviewUrl( {
    objectUrl: 'https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/test.pptx',
    credentials: {      // If the preview file is private, the request needs to carry the access credential.
        secretId: '',
        secretKey: '',
        authorization: 'q-sign-algorithmxxxxxxxxxxxxxxx',
    },
    copyable: 0,  // Whether the file content can be copied
    htmlwaterword: ''  // Watermark content
})
console.log(url)

    The configuration items are as described below:

    Configuration Item Description Required
    objectUrl The URL of the object that needs to be previewed, such as https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/test.pptx. Yes
    credentials If the object to be previewed is private, you need to pass in credentials as the access credential. You can pass in the calculated request signature (authorization) or your secretId and secretKey (not recommended as placing a permanent key on the frontend has security risks). No
    credentials.authorization Object download signature. For more information, see Request Signature. No
    credentials.secretId Your secretId, which can be obtained on the Manage API Key page in the CAM console. No
    credentials.secretKey Your secretKey, which can be obtained on the Manage API Key page in the CAM console. No
    copyable Whether the file content is copyable. Valid values: 1 (yes), 0 (no). No
    htmlwaterword Watermark text, which must be URL-safe Base64-encoded as described in FAQs and is empty by default. No
    htmlfillstyle Watermark RGBA (color and transparency), which must be URL-safe Base64-encoded as described in FAQs and is rgba(192,192,192,0.6) by default. No
    htmlfront Watermark text style, which must be URL-safe Base64-encoded as described in FAQs and is bold 20px Serif by default. No
    htmlrotate Rotation angle of the watermark text in degrees. Value range: 0–360. Default value: 315. No
    htmlhorizontal Horizontal spacing of the watermark text in px. Default value: 50. No
    htmlvertical Vertical spacing of the watermark text in px. Default value: 100. No

    Option 2. Directly request to get

    Sample request
    GET /<ObjectKey>?ci-process=doc-preview&dstType=html&weboffice_url=1&sign=AuthString HTTP/1.1 HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
    Request parameters
    Parameter Description Required
    ci-process Preview parameter, which is fixed at doc-preview. Yes
    dstType Preview type. To generate HTML files for preview, enter html. Yes
    weboffice_url Whether to get the preview URL. Valid values: 1 (return the preview URL and token information); 2 (return the token information only). If this parameter is not specified, the file will be directly previewed. No
    tokenuid Whether to get the token. A token will be generated and returned along with its validity period based on the information passed in such as tokenuid and file information. If this parameter is not specified, the token information won't be returned. No
    sign Object download signature, which must be URL-encoded. If the previewed object is privately readable, the signature needs to be passed in. For more information, see Request Signature. No
    copyable Whether the file content is copyable. Valid values: 1 (yes), 0 (no). No
    htmlwaterword Watermark text, which must be URL-safe Base64-encoded as described in FAQs and is empty by default. No
    htmlfillstyle Watermark RGBA (color and transparency), which must be URL-safe Base64-encoded as described in FAQs and is rgba(192,192,192,0.6) by default. No
    htmlfront Watermark text style, which must be URL-safe Base64-encoded as described in FAQs and is bold 20px Serif by default. No
    htmlrotate Rotation angle of the watermark text in degrees. Value range: 0–360. Default value: 315. No
    htmlhorizontal Horizontal spacing of the watermark text in px. Default value: 50. No
    htmlvertical Vertical spacing of the watermark text in px. Default value: 100. No
    Sample response
    HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 478
Date: Thu, 25 Feb 2021 07:44:37 GMT
Status: 200 OK
x-cos-request-id: NjAzNzU1NjVfY2MxZTIzMDlfNzc5NF8yMDQ5****

{
      "PreviewUrl": "https://prvsh.myqcloud.com/office/p/xxxx?_w_provider=XXX"
}

    4. Initialize

    During initialization, the JS-SDK will create an iframe under the configured mount node and automatically initialize relevant data and events.

    var demo = COSDocPreviewSDK.config({
   url: 'Online file preview URL',  // The online preview URL of the file obtained in step 3
})
// If special processing needs to be performed on the iframe, you can get the DOM object of the iframe as follows:
console.log(demo.iframe)
// File open result
demo.on('fileOpen', function(data) {
   console.log(data.success)
})

    5. Configure the mount node

    The mount node is the node mounted when the JS-SDK inserts the iframe. It is configurable during initialization.

    <div class="custom-mount"></div>

    var demo = COSDocPreviewSDK.config({
   url: 'Online file preview URL',    // The online preview URL of the file obtained in step 3
   mount: document.querySelector('.custom-mount')    // Mount node. By default, the `body` node will be mounted to. You can customize the mount node as needed.
})

    After initialization is completed, the JS-SDK will automatically insert an iframe under the mount node.

    <div class="custom-mount">
   <iframe src="..."></iframe>
</div>

    6. Authenticate the token

    If no token is used, the signature validity period will be used for authentication by default. Once the signature expires, the file cannot be previewed.
    If a token is used for authentication, token authentication and refresh can be performed continuously during preview, and you can control the preview authorization on your own.

    Token authentication consists of the following three steps:

    1. Get the token.

    Sample request

    GET /<ObjectKey>?ci-process=doc-preview&dstType=html&weboffice_url=2&tokenuid=test&sign=AuthString HTTP/1.1 HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date

    Sample response

    HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 108
Date: Tue, 21 Jun 2022 10:41:10 GMT
Status: 200 OK
x-cos-request-id: NjJiMWEwNDZfMTgyMjYyNjRfYmRlYl9iNTAw****

{
   Token: "ChAJj2vNRiHTc8reToMmJ7T2EJ7FxpUGGhS1mPJanpN03u8PSB17/YKBA/Vo****"
   TokenExpireTime: "1655808670"
}

    1. Set the token.

      Note：

      To avoid frequent token refresh, we recommend you set timeout to over 10 minutes. To prevent the refresh request from timing out, the JS-SDK will refresh the token several minutes in advance.

      var demo = COSDocPreviewSDK.config({
url: 'Online file preview URL',  // The online preview URL of the file obtained in step 3
})
// Set the token
demo.setToken({
token: 'yourToken', // Enter the obtained token
timeout: 10 * 60 * 1000, // Timeout period of the token in milliseconds. To avoid frequent refresh, we recommend you set it to over 10 minutes. The JS-SDK will call the token refresh method `refreshToken` before timeout.
});

    2. Configure the refreshToken method to automatically refresh the token upon timeout.
      The refreshToken method needs to request the token refresh method encapsulated on your server. The server can encapsulate the above token acquisition method (for more information, see Get the token).
      Taking the server method http://your.server.com/refreshToken as an example, configure refreshToken as follows:

      // Get the token
const refreshToken = () => {
// Call the method encapsulated on the server to get the token information
const tokenInfo = await $.get('http://your.server.com/refreshToken')
// `Promise` or `return { token, timeout }` can be returned.
return {
token: tokenInfo.token, // The token to be set, which is required.
timeout: 10 * 60 * 1000, //  The token timeout period in milliseconds, which is required.
};
};
var demo = COSDocPreviewSDK.config({
url: 'Online file preview URL',  
refreshToken    // Automatic token refresh method
})
// Set the token
demo.setToken({
token: 'yourToken', // Enter the obtained token
timeout: 10 * 60 * 1000   // Token timeout period in milliseconds
});

    Samples

    • For the sample code of online preview of a text file, see the DOC file preview demo at GitHub.
    • For the sample code of online preview of a presentation file, see the PPT file preview demo at GitHub.
    • For the sample code of online preview of a spreadsheet file, see the Excel file preview demo at GitHub.
    • For the sample code of online preview of a PDF file, see the PDF file preview demo at GitHub.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy