This topic describes how to install OSS Browser.js SDK.

Download the SDK

Demos in official documents are based on SDK 6.X. For SDKs earlier than 6.X, see Documents for 5.X SDK. For more information about how to upgrade your SDK to 6.X, see Upgrade document.

Environment preparations

  • Requirements
    • You must have activated Alibaba Cloud OSS. If you do not know about Alibaba Cloud OSS, log on to the OSS Product Homepage. For more information, see Product Overview.
    • You must have created an AccessKeyID and an AccessKeySecret. Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you follow the Alibaba Cloud Security Best Practices. If you deploy the service on the server, you can use an RAM sub-account or STS for API access or daily O&M management and control. If you deploy the service on the client, we recommend you use STS for API access. For more information, see Access control.
  • Environment requirements

    The OSS BrowserJS-SDK is built on the Node.js environment. It generates codes that apply to browsers through Browserify and Babel.

    However, because of the special natures of the browser environment, some features cannot be used:

    • Stream upload: The chunked encoding cannot be set in browsers. The multipart upload can be used instead.
    • Operations on local files: You cannot directly operate on local file systems in the browser. You can download the file using a signed URL.
    • Bucket-related operations (listBuckets/BucketACL/BucketLogging). Since OSS does not support bucket-related cross-origin requests currently, you can perform bucket-related operations in the console.

Usage

The OSS BrowserJS-SDK supports both synchronous and asynchronous usages.

  • Synchronous mode: Synchronize the asynchronous mode based on async/await in the ES7 standard.

  • Asynchronous mode: Similar to callback. The API returns Promise. The .then() method is used to process the returned result and the .catch() method is used to process errors.

new OSS() is used to create a client both in the synchronous mode and asynchronous mode.

Here are the examples of uploading a file and then downloading the file immediately in the two modes:

  • Synchronous mode
    // Create an OSS client instance. For detailed parameters, see the configuration items described in the documents.
    let client = new OSS(...);
    
    async function put () {
      try {
        // object indicates the name of the uploaded object, which can be customized.
        // file indicates the file that needs to be upload in the browser. The HTML and Blob formats are supported.
        let r1 = await client.put('object', file);
        console.log('put success: %j', r1);
        let r2 = await client.get('object');
        console.log('get success: %j', r2);
      } catch (e) {
        console.error('error: %j', e);
      }
    }
    
    put();
    
  • Asynchronous mode
    // Create an OSS client instance. For detailed parameters, see the configuration items described in the documents.
    let client = new OSS(...);
    
    // object indicates the name of the uploaded object, which can be customized.
    // file indicates the file that needs to be upload in the browser. The HTML and Blob formats are supported.
    client.put('object', file).then(function (r1) {
      console.log('put success: %j', r1);
      return client.get('object');
    }).then(function (r2) {
      console.log('get success: %j', r2);
    }).catch(function (err) {
      console.error('error: %j', err);
    });
    

Installation

  • Usage in browsers

    Supported browsers:

    • IE (>=10) and Edge
    • Mainstream Chrome/Firefox/Safari versions
    • Mainstream Android/iOS/WindowsPhone versions

    Browser.js SDK can be installed in the following methods:

    • Browser introduction:
      Notice Some browsers do not support promise, so a promise compatibility library must be introduced. For example, promise-polyfill must be introduced for IE10 and IE11.
      <!-- Introduce online resources -->
      <script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
      
      -- Introduce local resources -->
      <script src="./aliyun-oss-sdk-x.x.x.min.js"></script>
      
      Note
      • x.x.x represents the version number. For more information about the specific version, see here.
      • The introduction of online resources depends on the stability of the CDN server. Users are recommended to introduce resources offline, that is, through local resources or self-built.

      You can use the OSS.Wrapper object in the code:

      <script type="text/javascript">
        let client = new OSS({
          region: '<oss region>',
      	//Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you access an API using STS by following the Alibaba Cloud Security Best Practices.
          accessKeyId: '<Your accessKeyId(STS)>',
          accessKeySecret: '<Your accessKeySecret(STS)>',
          stsToken: '<Your securityToken(STS)>',
          bucket: '<Your bucket name>'
        });
      </script>
      
    • Use npm to install the SDK:
      npm install ali-oss
      

      After the installation is completed, you can reference it using “import” or “require”. The require mode is not supported by browsers. Therefore, you must use packaging tools, such as webpack and browserify in the development environment.

      let OSS = require('ali-oss');
      
      let client = new OSS({
        region: '<oss region>', 
        //Since the Alibaba Cloud account AccessKey gives you permission to access all APIs, we recommend that you follow the Alibaba Cloud Security Best Practices. If you deploy the service on the server, use an RAM sub-account or STS, and if you deploy the service on the client, use STS.
        accessKeyId: '<Your accessKeyId>',
        accessKeySecret: '<Your accessKeySecret>',
        bucket: '<Your bucket name>'
      });
      
    • Use Bower:

      For web projects, you can install the SDK through the Bower:

      bower install ali-oss
      

      Then you can add the <script> tag in the webpage:

      <script src="bower_components/ali-oss/dist/aliyun-oss-sdk.min.js"></script>