tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Cloud Object Storage
    Documentation
    Download PDF

    Custom Configuration Overview

    Last updated: 2024-06-12 15:27:03
    Download PDF

      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"
      }
      2. 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.
      });
      3. 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.
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy