Implement resumable file uploads with Browser.js SDK - Object Storage Service

Resumable upload uses checkpoints to track multipart upload progress. If an upload is interrupted by a network error or a program crash, it resumes from the last checkpoint instead of starting over.

Prerequisites

Before you begin, ensure that you have:

OSS SDK for Browser.js installed or loaded
A bucket with CORS rules configured for browser access
Temporary access credentials obtained from Security Token Service (STS)

Browsers require CORS rules on the bucket to allow cross-origin requests. For setup instructions, see Installation.

To avoid exposing your AccessKey pair in browser code, use temporary access credentials from STS. The credentials include an AccessKey ID, an AccessKey secret, and a security token. For details, see Use STS for temporary access authorization.

Install the SDK

If you use a packaging tool such as Webpack or Browserify, install the SDK with npm:

npm install ali-oss

To load the SDK directly in a browser, add the following script tag:

<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>

How it works

multipartUpload splits the file into parts and uploads them. On each progress callback, the SDK provides a checkpoint object that records which parts have been uploaded.

To resume an interrupted upload, pass the saved checkpoint back to multipartUpload. The upload continues from the last completed part.

Upload, pause, and resume

The following example builds a page with Upload, Pause, and Resume Upload buttons. It demonstrates how to start a multipart upload, pause it, and resume from the checkpoint.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <button id="submit">Upload</button>
    <button id="pause">Pause</button>
    <button id="resume">Resume Upload</button>
    <!-- Load the OSS SDK -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      // Initialize the OSS client with STS temporary credentials.
      // Replace the placeholder values with your actual credentials.
      const client = new OSS({
        // Region where the bucket is located, for example: oss-cn-hangzhou
        region: '<your-region>',
        // Enable Signature Version 4 (recommended)
        authorizationV4: true,
        // Temporary AccessKey ID from STS
        accessKeyId: '<your-access-key-id>',
        // Temporary AccessKey secret from STS
        accessKeySecret: '<your-access-key-secret>',
        // Security token from STS
        stsToken: '<your-security-token>',
        // Bucket name, for example: examplebucket
        bucket: '<your-bucket-name>',
      });

      // Generate a 100 MB test file.
      // In production, replace this with a File object from a file input element.
      const fileContent = Array(1024 * 1024 * 100).fill('a').join('');
      const file = new File([fileContent], 'multipart-upload-file');

      // The object key (path) in the bucket, for example: exampledir/exampleobject.txt
      const name = 'test.txt';

      // Stores the checkpoint from the last progress callback.
      // Pass this to multipartUpload to resume an interrupted upload.
      let abortCheckpoint;

      const submit = document.getElementById('submit');
      const pause = document.getElementById('pause');
      const resume = document.getElementById('resume');

      // Start the upload when the user clicks Upload.
      submit.addEventListener('click', () => {
        client
          .multipartUpload(name, file, {
            progress: (p, cpt, res) => {
              // Save the latest checkpoint after each part uploads.
              abortCheckpoint = cpt;
              // p is a value between 0 and 1 representing upload progress.
              console.log('Progress:', p * 100, '%');
            },
          })
          .then((result) => console.log('Upload complete:', result));
      });

      // Pause the upload when the user clicks Pause.
      pause.addEventListener('click', () => {
        client.cancel();
      });

      // Resume the upload from the last checkpoint.
      const resumeUpload = async () => {
        try {
          const result = await client.multipartUpload(name, file, {
            // Pass the saved checkpoint to resume from the last completed part.
            checkpoint: abortCheckpoint,
            progress: (p, cpt, res) => {
              // Keep updating the checkpoint in case the upload is interrupted again.
              abortCheckpoint = cpt;
              console.log('Progress:', p * 100, '%');
            },
          });
          console.log('Upload complete:', result);
        } catch (e) {
          console.error('Upload error:', e);
        }
      };

      // Resume the upload when the user clicks Resume Upload.
      resume.addEventListener('click', async () => {
        await resumeUpload();
      });
    </script>
  </body>
</html>

Placeholder reference

Replace the following placeholders with your actual values before running the example:

Placeholder	Description	Example
`<your-region>`	Region ID where the bucket is located	`oss-cn-hangzhou`
`<your-access-key-id>`	Temporary AccessKey ID from STS	`STS.NUg...`
`<your-access-key-secret>`	Temporary AccessKey secret from STS	`3D7x...`
`<your-security-token>`	Security token from STS	`CAIS...`
`<your-bucket-name>`	Name of the bucket	`examplebucket`

References

For the complete sample code for resumable uploads, see the GitHub example.