Download and Installation

Relevant resources

• Download the COS XML SDK for WeChat Mini Program source code here.
• Download the XML SDK for WeChat Mini Program here.
• Download the demo here.
• Find the complete sample code here.
• For the SDK changelog, please see Changelog.

Environmental dependency

1. This SDK is only applicable to WeChat Mini Program.
2. Log in to the COS console, create a bucket, and get the bucket name and region information.
3. Log in to the CAM console and get your project's SecretId and SecretKey.

Note：

For the definitions of parameters such as SecretId, SecretKey, and Bucket, please see COS Glossary.

Installing SDK

There are two ways to install the SDK for WeChat Mini Programs: manual installation and installation through npm as detailed below.

Installing manually

Copy the cos-wx-sdk-v5.js file in the source code directory to any path in the root directory of your WeChat Mini Program code and reference it using a relative path:

var COS = require('./lib/cos-wx-sdk-v5.js')

Installing through npm

If the code of your WeChat Mini Program is packaged with webpack, install the dependencies through npm:

npm install cos-wx-sdk-v5

The WeChat Mini Program code is referenced with var COS = require('cos-wx-sdk-v5');.

Getting Started

Configuring domain name allowlist for WeChat Mini Program

To request COS in your WeChat Mini Program, you need to log in to the WeChat Official Accounts Platform and configure the domain name allowlist in Development > Basic Configuration > Server Domain. The SDK uses the following two APIs:

1. For cos.postObject, use the wx.uploadFile API.
2. For other methods, use the wx.request API.

For both methods, you need to configure the COS domain name. There are two forms of domain name allowlists.

1. For standard requests, you can configure the bucket domain name as the allowlist domain name, for example:
   examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com.
2. If multiple buckets are used in your WeChat Mini Program, you can choose to use suffixed COS requests by passing in ForcePathStyle: true when instantiating the SDK. In this case, you need to configure the region domain name as the allowlist, such as cos.ap-guangzhou.myqcloud.com.

Initialization

var COS = require('./lib/cos-wx-sdk-v5.js')

var cos = new COS({
    // ForcePathStyle: true, // If multiple buckets are used, you can use suffixed requests to reduce the number of allowed domain names to be configured; the region domain name will be used for requests
    getAuthorization: function (options, callback) {
        // Get a temporary key asynchronously
        wx.request({
            url: 'https://example.com/server/sts.php',
            data: {
                bucket: options.Bucket,
                region: options.Region,
            },
            dataType: 'json',
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                    StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                    ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
                });
            }
        });
    }
});

// The COS instance can then be used to call a COS request
// TODO

Configuration items

Samples

Create a COS SDK instance in the following methods:

• Method 1 (recommended): the backend gets a temporary key and sends it to the frontend for signature calculation.

var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // Server examples for JS and PHP: https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/
        // For server-side examples for other programming languages, please see the COS SDK for STS: https://github.com/tencentyun/qcloud-cos-sts-sdk
        // For the STS documentation, visit https://intl.cloud.tencent.com/document/product/436/14048?from_cn_redirect=1
        wx.request({
            url: 'https://example.com/server/sts.php',
            data: {
                // The required parameters can be obtained from options
            },
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                    StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                    ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
                });
            }
        });
    }
});

Note：

For more information on how to generate and use a temporary key, please see Generating and Using Temporary Keys.

• Method 2 (recommended): the permission is controlled in a more refined manner. The backend gets a temporary key and sends it to the frontend. The frontend reuses the key only for the same request, and the backend can finely manage the permission through Scope.

var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // Server example: https://github.com/tencentyun/qcloud-cos-sts-sdk/edit/master/scope.md
        wx.request({
            url: 'https://example.com/server/sts-scope.php',
            data: JSON.stringify(options.Scope),
            success: function (result) {
                var data = result.data;
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                    StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                    ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
                    ScopeLimit: true, // Refined permission control needs to be set to true, limiting that the key can be reused only for the same request
                });
            }
        });
    }
});

Note：

For more information on how to generate and use a temporary key, please see Generating and Using Temporary Keys.

• Method 3 (not recommended): the frontend needs to get a signature through getAuthorization before each request, and the backend uses a permanent or temporary key to calculate the signature and returns it to the frontend. This method makes it difficult to control the permission to multipart uploads and thus is not recommended.

var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // The server obtains a signature. For more information, please see the COS SDK for the corresponding programming language: https://intl.cloud.tencent.com/document/product/436/6474
        // Note: there may be a security risk associated with this method. The backend needs to strictly control the permission through method and pathname, such as prohibiting put /
        wx.request({
            url: 'https://example.com/server/auth.php',
            data: JSON.stringify(options.Scope),
            success: function (result) {
                var data = result.data;
                if (!data || !data.authorization) return console.error('authorization invalid');
                callback({
                    Authorization: data.authorization,
                    // XCosSecurityToken: data.sessionToken, // If a temporary key is used, sessionToken needs to be passed to XCosSecurityToken
                });
            }
        });
    },
});

• Method 4 (not recommended): the frontend uses a permanent key to calculate the signature. This method can be used for frontend debugging. If you use this method, be sure to avoid key disclosure.

var cos = new COS({
    SecretId: 'COS_SECRETID',
    SecretKey: 'COS_SECRETKEY',
});

Constructor parameter description

getAuthorization callback function descriptions (using method 1)

getAuthorization: function(options, callback) { ... }

getAuthorization callback parameter descriptions:

After the temporary key is obtained, the callback returns an object. The attributes of the returned object are as shown below:

getAuthorization callback function description (using method 2)

getAuthorization: function(options, callback) { ... }

getAuthorization callback parameters:

Once the getAuthorization callback function is finished, it returns one of the following:
Format 1. An Authorization string.
Format 2. An object whose attributes are listed as follows:

Getting authentication credential

There are three ways to get the authentication credentials for your instance by passing in different parameters during instantiation:

1. During instantiation, pass in your SecretId and SecretKey, and each time a signature is required, it will be internally calculated by the instance.
2. During instantiation, pass in the getAuthorization callback function, and each time a signature is required, it will be calculated and returned to the instance through this callback.
3. During instantiation, pass in the getSTS callback, and each time a temporary key is required, it will be returned to the instance by this callback for signature calculation within the instance during each request.

Below are some examples of common APIs. For more detailed initialization methods, please see the examples in the demo.

Creating bucket

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
}, function (err, data) {
    console.log(err || data);
});

Note：

If you need to create a bucket in the WeChat Mini Program, but the bucket name is unknown, you cannot configure the bucket name as a domain name allowlist. Instead, you can use the suffix to call it. For applicable measures, please see FAQs.

Querying bucket list

cos.getService(function (err, data) {
    console.log(data && data.Buckets);
});

Uploading object

The WeChat Mini Program upload API "wx.uploadFile" only supports POST requests. To upload files with the SDK, you need to use the postObject API. If only the file uploading API is needed in your WeChat Mini Program, we do not recommend you reference the SDK. For more information, please see demo.

// First, select the file to get the temporary path
wx.chooseImage({
    count: 1, // Default value: 9
    sizeType: ['original'], // You can specify whether to use the original or compressed image. The original is used by default value.
    You can specify whether the source is an album or camera. Both are included by default.
    success: function (res) {
        var filePath = res.tempFiles[0].path;
        var filename = filePath.substr(filePath.lastIndexOf('/') + 1);
        cos.postObject({
            Bucket: 'examplebucket-1250000000',
            Region: 'ap-beijing',
            Key: 'destination path/' + filename,
            FilePath: filePath,
            onProgress: function (info) {
                console.log(JSON.stringify(info));
            }
        }, function (err, data) {
            console.log(err || data);
        });
    }
});

Querying object list

cos.getBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Prefix: 'exampledir/', // Pass in the file prefixes to be listed here
}, function (err, data) {
    console.log(err || data.Contents);
});

Downloading object

Note：

This API is used to read the object content. If you need to launch a browser to download the file, you can get the URL through cos.getObjectUrl and then start a download in the browser. For more information, please see Pre-signed URL.

cos.getObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: 'exampleobject.txt',
}, function (err, data) {
    console.log(err || data.Body);
});

Deleting object

cos.deleteObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: 'picture.jpg',
}, function (err, data) {
    console.log(err || data);
});