Object Storage Service:Install the OSS Browser.js SDK

Prerequisites

• Use a RAM user or STS for access

  Your Alibaba Cloud account's AccessKey pair grants full access to all APIs. As a security best practice, we strongly recommend against using your AccessKey pair directly. For server-side applications, you can use a RAM user or STS for API access and routine operations. For client-side applications, you must use STS for API access. For more information, see access control.

• Configure cross-origin resource sharing (CORS)

  When you access OSS directly from a browser, you must configure CORS rules for your bucket as follows:

  • Origin: Specify an exact domain name, such as https://www.aliyun.com, or a domain name that includes the asterisk (*) wildcard character, such as https://*.aliyun.com.

  • Allowed Methods: Select methods based on your use case. For example, select PUT for multipart uploads and DELETE to delete objects.

  • Allowed Headers: Set this to *.

  • Exposed Headers: Set headers based on your use case. For example, you might need to expose ETag, x-oss-request-id, and x-oss-version-id.

  

  For more information, see Configure CORS.

Limitations

The OSS SDK for Browser.js uses Browserify and Babel to generate browser-compatible code. Due to the limitations of the browser environment, the following features are not supported:

• Streaming upload: Chunked encoding cannot be configured in a browser. Use multipart upload instead.

• Local file operations: You cannot directly access the local file system from a browser. Use signed URLs to download objects.

• OSS does not support bucket-related cross-origin requests. Perform bucket-related operations in the console.

Download the SDK

The examples in the official documentation are based on SDK v6.x. For versions earlier than 6.x, see the 5.x development documentation. To upgrade to 6.x, see the upgrade guide.

• GitHub repository

• API operations

• ChangeLog

Install the SDK

• Supported browsers

  • Internet Explorer 10 and later

  • Edge

  • Major versions of Chrome, Firefox, and Safari

  • Default browsers on major versions of Android, iOS, and Windows Phone

• Installation methods

  You can install the OSS SDK for Browser.js in one of the following ways.

  Import in a browser

  Important

  Some browsers, such as Internet Explorer 10 and 11, do not natively support Promises. You must include a Promise polyfill library, such as promise-polyfill.

  <!-- Import from a CDN -->
  <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"></script>      
  <!-- Import from a local file -->
  <script src="./aliyun-oss-sdk-6.20.0.min.js"></script>

  Note

  • Importing from a CDN depends on the stability of the CDN server. We recommend importing the SDK from a local file or building it yourself.

  • When you import from a local file, set the src attribute to the relative path of the file.

  • This topic uses version 6.20.0 as an example. For more versions, see ali-oss.

  Use the OSS object in your code:

  Important

  The OSS SDK for Browser.js typically runs in a browser environment. To avoid exposing your Alibaba Cloud account's AccessKey pair (AccessKey ID and AccessKey secret), we strongly recommend using temporary access credentials for OSS operations.

  Temporary access credentials include a temporary AccessKey pair (AccessKey ID and AccessKey secret) and a security token. You can obtain temporary access credentials by calling the STS AssumeRole operation or by using STS SDKs for various programming languages. For information about how to build an STS service, see Use temporary access credentials provided by STS to access OSS.

  <script type="text/Browser.jsscript">
    const client = new OSS({
      // Set region to the region where the bucket is located. For example, if your bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
      region: 'yourRegion',
      // Enable V4 signature.
      authorizationV4: true,
      // The temporary AccessKey pair (AccessKey ID and AccessKey secret) obtained from STS.
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // The security token obtained from STS.
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from your STS service.
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // The interval for refreshing temporary access credentials, in milliseconds.
      refreshSTSTokenInterval: 300000,
      // The bucket name.
      bucket: 'examplebucket'
    });
  </script>                           

  Install with npm

  npm install ali-oss

  After installation, you can import the package using import or require. Since browsers do not natively support the require module format, you must use a bundler, such as webpack or browserify, in your development environment.

  const OSS = require('ali-oss');
  
  const client = new OSS({
      // Set region to the region where the bucket is located. For example, if your bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
      region: 'yourRegion',
      // Enable V4 signature.
      authorizationV4: true,
      // The temporary AccessKey pair (AccessKey ID and AccessKey secret) obtained from STS.
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // The security token obtained from STS.
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from your STS service.
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // The interval for refreshing temporary access credentials, in milliseconds.
      refreshSTSTokenInterval: 300000,
      // The bucket name.
      bucket: 'examplebucket'
  });

Usage modes

The OSS SDK for Browser.js supports synchronous and asynchronous programming models. In both models, you create a client instance with new OSS().

// Create a client instance.
const client = new OSS(...);

async function put () {
  try {
    // The name of the object to upload to OSS.
    // The file to upload from the browser. It can be an HTML5 File or Blob object.
    const r1 = await client.put('object', file);
    console.log('put success: %j', r1);
    const r2 = await client.get('object');
    console.log('get success: %j', r2);
  } catch (e) {
    console.error('error: %j', e);
  }
}

put();                    

// Create a client instance.
const client = new OSS(...);

// The name of the object to upload to OSS.
// The file to upload from the browser. It can be an HTML5 File or Blob object.
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);
});