How to perform a simple upload using the Browser.js SDK - Object Storage Service

Use the putObject method to upload a file, BLOB data, or buffer directly to Object Storage Service (OSS) from a browser. Simple upload sends the entire object in a single request and does not support upload progress callbacks.

Simple upload is suited for small files. If you need upload progress tracking, or if files may exceed network reliability limits, use multipart upload (Browser.js SDK) or resumable upload (Browser.js SDK) instead.

Prerequisites

Before you begin, ensure that you have:

Installed OSS SDK for Browser.js. For details, see Installation.
Configured CORS rules for the bucket. Without CORS rules, the browser rejects cross-origin requests. For configuration steps, see Configure CORS.
Obtained temporary access credentials from Security Token Service (STS). The credentials include an AccessKey ID, an AccessKey secret, and a security token. For details, see Use STS for temporary access authorization.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles have no permissions by default and must be granted access through a RAM Policy or bucket policy.

API	Action	When required
PutObject	`oss:PutObject`	Always required
PutObject	`oss:PutObjectTagging`	Required when specifying object tags via `x-oss-tagging`
PutObject	`kms:GenerateDataKey`	Required when using `X-Oss-Server-Side-Encryption: KMS`
PutObject	`kms:Decrypt`	Required when using `X-Oss-Server-Side-Encryption: KMS`

Usage notes

If you use a packaging tool such as Webpack or Browserify, install the SDK by running npm install ali-oss.
Always use STS temporary access credentials in browser environments. Embedding your primary AccessKey pair in client-side code exposes it to end users.

Upload an object

The following examples show how to upload different data types to OSS using the Browser.js SDK. All examples use STS temporary credentials.

Initialize the client

<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
<script>
  const client = new OSS({
    // Region where the bucket is located. Example: oss-cn-hangzhou
    region: "<your-region>",
    authorizationV4: true,
    // STS temporary credentials — do not use your primary AccessKey pair in browsers
    accessKeyId: "<your-sts-access-key-id>",
    accessKeySecret: "<your-sts-access-key-secret>",
    stsToken: "<your-sts-security-token>",
    bucket: "<your-bucket-name>",
  });
</script>

Replace the placeholders with your actual values:

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

Upload a file selected by the user

Use an <input type="file"> element to let the user pick a local file, then pass the File object to client.put.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>OSS simple upload</title>
  </head>
  <body>
    <input id="file" type="file" />
    <button id="upload">Upload</button>
    <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
    <script>
      const client = new OSS({
        region: "<your-region>",
        authorizationV4: true,
        accessKeyId: "<your-sts-access-key-id>",
        accessKeySecret: "<your-sts-access-key-secret>",
        stsToken: "<your-sts-security-token>",
        bucket: "<your-bucket-name>",
      });

      async function putObject(data) {
        try {
          // Specify the full path of the object, excluding the bucket name.
          // Example: "exampledir/exampleobject.txt"
          const result = await client.put("exampledir/exampleobject.txt", data, {
            meta: { temp: "demo" },
            mime: "json",
            headers: { "Content-Type": "text/plain" },
          });
          console.log(result);
        } catch (e) {
          console.error(e);
        }
      }

      document.getElementById("upload").addEventListener("click", () => {
        const file = document.getElementById("file").files[0];
        putObject(file);
      });
    </script>
  </body>
</html>

The options parameter in client.put accepts the following fields:

Field	Description	Example
`meta`	Custom metadata attached to the object	`{ temp: "demo" }`
`mime`	MIME type of the object	`"json"`
`headers`	HTTP headers sent with the request	`{ "Content-Type": "text/plain" }`

Upload BLOB data

A BLOB (Binary Large Object) is an in-memory binary payload. Create a Blob and pass it to client.put.

const data = new Blob(["Hello OSS"]);
const result = await client.put("exampledir/exampleobject.txt", data);
console.log(result);

Upload a buffer

Use OSS.Buffer to upload an in-memory buffer.

const data = new OSS.Buffer(["Hello OSS"]);
const result = await client.put("exampledir/exampleobject.txt", data);
console.log(result);

FAQ

Can I track upload progress with simple upload?

No. Simple upload does not support progress callbacks. To track upload progress, use multipart upload (Browser.js SDK) or resumable upload (Browser.js SDK).

What's next

For the complete sample code, see the GitHub example.
For the PutObject API reference, see PutObject.