tencent cloud

Cloud Object Storage

Release Notes and Announcements
Release Notes
Announcements
Product Introduction
Overview
Features
Use Cases
Strengths
Concepts
Regions and Access Endpoints
Specifications and Limits
Service Regions and Service Providers
Billing
Billing Overview
Billing Method
Billable Items
Free Tier
Billing Examples
Viewing and Downloading Bill
Payment Overdue
FAQs
Getting Started
Console
Getting Started with COSBrowser
User Guide
Creating Request
Bucket
Object
Data Management
Batch Operation
Global Acceleration
Monitoring and Alarms
Operations Center
Data Processing
Content Moderation
Smart Toolbox
Data Processing Workflow
Application Integration
User Tools
Tool Overview
Installation and Configuration of Environment
COSBrowser
COSCLI (Beta)
COSCMD
COS Migration
FTP Server
Hadoop
COSDistCp
HDFS TO COS
GooseFS-Lite
Online Tools
Diagnostic Tool
Use Cases
Overview
Access Control and Permission Management
Performance Optimization
Accessing COS with AWS S3 SDK
Data Disaster Recovery and Backup
Domain Name Management Practice
Image Processing
Audio/Video Practices
Workflow
Direct Data Upload
Content Moderation
Data Security
Data Verification
Big Data Practice
COS Cost Optimization Solutions
Using COS in the Third-party Applications
Migration Guide
Migrating Local Data to COS
Migrating Data from Third-Party Cloud Storage Service to COS
Migrating Data from URL to COS
Migrating Data Within COS
Migrating Data Between HDFS and COS
Data Lake Storage
Cloud Native Datalake Storage
Metadata Accelerator
GooseFS
Data Processing
Data Processing Overview
Image Processing
Media Processing
Content Moderation
File Processing Service
File Preview
Troubleshooting
Obtaining RequestId
Slow Upload over Public Network
403 Error for COS Access
Resource Access Error
POST Object Common Exceptions
API Documentation
Introduction
Common Request Headers
Common Response Headers
Error Codes
Request Signature
Action List
Service APIs
Bucket APIs
Object APIs
Batch Operation APIs
Data Processing APIs
Job and Workflow
Content Moderation APIs
Cloud Antivirus API
SDK Documentation
SDK Overview
Preparations
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
Mini Program SDK
Error Codes
Harmony SDK
Endpoint SDK Quality Optimization
Security and Compliance
Data Disaster Recovery
Data Security
Cloud Access Management
FAQs
Popular Questions
General
Billing
Domain Name Compliance Issues
Bucket Configuration
Domain Names and CDN
Object Operations
Logging and Monitoring
Permission Management
Data Processing
Data Security
Pre-signed URL Issues
SDKs
Tools
APIs
Agreements
Service Level Agreement
Privacy Policy
Data Processing And Security Agreement
Contact Us
Glossary

Custom Configuration Overview

PDF
Focus Mode
Font Size
Last updated: 2026-01-13 16:34:02

Feature Overview

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

Architecture





Operating Environments

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 a package

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 described as follows:
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 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 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 and renewal can be completed in the following three steps. For more information, see the demo.
1. Get the token. Request sample
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).
4. 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
});


Examples

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.
For the sample code of token authentication and renewal, see the token authentication and renewal demo at GitHub.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback