Getting Started

Download and Installation

Relevant Resources

• The COS XML SDK for WeChat Mini Program source code can be downloaded here.
• The demo can be downloaded here.

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.

For more information on the meanings of parameters such as SecretId, SecretKey, and Bucket contained herein and how to get them, see COS Glossary.

Installing the SDK

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

Manual Installation

Copy the cos-wx-sdk-v5.js file in the source code directory to the code directory of your WeChat Mini Program. The code can be referenced by a relative path:

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

Installing via npm

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

npm install cos-wx-sdk-v5

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

Getting Started

Configuring the WeChat Mini Program Whitelist

To request COS in the WeChat Mini Program, you need to log in to the WeChat Official Accounts Platform and configure the domain name whitelist in Development > Development Settings. 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 of them, you need to configure the COS domain name. There are two forms of domain name whitelists.

1. For standard requests, you can configure the bucket domain name as the whitelist domain name, for example:
   examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com。
2. If multiple buckets are used in the 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 whitelist, such as cos.ap-guangzhou.myqcloud.com.

Initialization

var cos = new COS({
    // ForcePathStyle: true, // If a lot of buckets are used, you can reduce the number of whitelisted domain names to be configured by enabling the suffix, and 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: 'text',
            success: function (result) {
                var data = result.data;
                var credentials = data.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                });
            }
        });
    }
});

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

Configuration Items

Use Cases

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 = require('cos-nodejs-sdk-v5');
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 examples for other programming languages, 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.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                });
            }
        });
    }
});

• 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.credentials;
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    ExpiredTime: data.expiredTime,
                    ScopeLimit: true, // Refined permission control needs to be set to true, limiting that the key can be reused only for the same request
                });
            }
        });
    }
});

• Method 3 (not recommended): The frontend needs to get a signature through getAuthorization before each request, and the backend uses a fixed 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, see the COS SDK for the corresponding programming language: https://intl.cloud.tencent.com/document/product/436/6474?from_cn_redirect=1
        // Note: There may be a security risk. 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;
                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 fixed key to calculate a signature. This method is suitable 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 Descriptions

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 Descriptions (Using Method 2)

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

getAuthorization function callback parameter descriptions

After the getAuthorization calculation is completed, the callback returns a signature string or an object:
If a signature string is returned, the string type is the credential field "Authorization" to be used by the authentication header of the request.
If an object is returned, the attributes of the object are as shown below:

Getting an Authentication Credential

You have three ways to obtain the authentication credentials for your instance by passing in different parameters during instantiation:

1. During instantiation, pass in the 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, 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 commonly used APIs. For more detailed initialization methods, see the examples in the demo.

Creating a Bucket

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

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 whitelist. Instead, you can use the suffix to call it. For applicable measures, see FAQs.

Querying Bucket List

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

Uploading an 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, it is recommended not to reference the SDK. For more information, see the demo.

// First, select the file to get the temporary path
wx.chooseImage({
    count: 1, // Default value: 9
    sizeType: ['original'], // You can specify whether the image is original or compressed. Default value: original
    sourceType: ['album', 'camera'], // You can specify whether the source is album or camera. Default value: both
    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 prefix of files to be listed here
}, function (err, data) {
    console.log(err || data.Contents);
});

Downloading an Object

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, see Pre-signed URL.

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

Deleting an Object

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