> For the complete documentation index, see [llms.txt](https://docs.viverse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viverse.com/developer-tools/javascript/javascript-storage.md).

# Storage SDK

JavaScript cloud save for PlayCanvas, three.js, and other browser JavaScript. For a Unity game, use the current VIVERSE Unity SDK for C#. Do not use this JavaScript SDK or a .jslib.

***

For a Unity game, use the current [VIVERSE Unity SDK](/developer-tools/unity/viverse-unity-sdk.md) for C#. Do not use this JavaScript SDK or a `.jslib` for normal Unity authentication, cloud save, multiplayer, leaderboard, or avatar integration.

> **BEFORE GETTING STARTED:** you must [authenticate with VIVERSE](/developer-tools/javascript/javascript-login.md), including App ID creation in VIVERSE Studio, before requesting Play SDK services.

## Initialize the \`storageClient\` instance

Before using any Storage SDK features, you must initialize the client instance. This global reference ensures that the Storage SDK is available throughout your application. A Unity game uses `CloudSaveClient` in the [VIVERSE Unity SDK](/developer-tools/unity/viverse-unity-sdk.md). Do not add a `.jslib` for this sample.

```
globalThis.storageClient = new globalThis.viverse.storage();
```

## Cloud Save API

The cloudsave API must then be initialized individually.

```
globalThis.cloudSaveClient = await storageClient.newCloudSaveClient(appId);
```

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-7940503160e25e879211b595f408e05a5ed20b3c%2Fstorage-client-cloudsave-1.png?alt=media" alt=""><figcaption></figcaption></figure>

### Set Player Data

Call setPlayerData() with a specific key-value pair within the player's data.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-019e60322a5a168586d0ea90b4f6361c96458a2a%2Fstorage-client-cloudsave-2.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
const keyA = 'coins';
const dataA = 100;
cloudSaveClient.setPlayerData(keyA, dataA, access_token);

const keyB = 'data';
const dataB = { "level": 10, "stages": { "1": { "score": 20 } } };
cloudSaveClient.setPlayerData(keyB, dataB, access_token);

// Possible return values:
// {
//    "success": true
// }
//     or
// {
//     "success": false,
//     "message": "error message"
// }
```

### Get Player Data

Retrieves the value of a specific key from the player's data.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-f794407f397509c53894f3569e6aa75aa9833ebf%2Fstorage-client-cloudsave-3.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
const key = 'coins';
cloudSaveClient.getPlayerData(key, access_token).then((res) => {
  console.log(res)
})

// Possible return values:
// 100
```

```
const key = 'data';
cloudSaveClient.getPlayerData(key, access_token).then((res) => {
  console.log(${JSON.stringify(res)})
})

// Possible return values:
// {
//     "level": 10,
//     "stages": {
//         "1": {
//             "score": 20
//         }
//     }
// }
```

```
const key = 'new';
cloudSaveClient.getPlayerData(key, access_token).then((res) => {
  console.log(res)
})

// Possible return values:
// null
```

### Save

Saves the provided data as a new version.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-b2618cc8a30e4b7b872df22ea5ae8aff95245e5d%2Fstorage-client-cloudsave-4.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
const dataB = { "level": 10, "stages": { "1": { "score": 20 } } };
cloudSaveClient.save(data, access_token);

// Possible return values:
// {
//     "success": true
// }
// {
//     "success": false,
//     "error": "error message"
// }
```

### Get All

Retrieves all saved versions of saved data.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-e89a1b2ad678513ef867b1e5db321ad65ed72101%2Fstorage-client-cloudsave-5.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
cloudSaveClient.getAll(access_token);

// Possible return values:
// [
//     {
//         "user_id": "4d0e91a3-f279-4616-b720-50fdab315bf4",
//         "app_id": "app_id",
//         "data": {
//             "level": 10,
//             "stages": {
//                 "1": {
//                     "score": 20
//                 }
//             }
//         },
//         "version": 1752564108,
//         "created_at": "2025-07-15T07:21:48.312Z"
//     }
// ]
```

### Get Latest

Retrieves the most recent version of saved data.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-54c3f8afdc1d4ed9c30329d79837be0ae81e7079%2Fstorage-client-cloudsave-6.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
cloudSaveClient.getLatest(access_token);

// Possible return values:
// {
//     "user_id": "4d0e91a3-f279-4616-b720-50fdab315bf4",
//     "app_id": "app_id",
//     "data": {
//         "level": 10,
//         "stages": {
//             "1": {
//                 "score": 20
//             }
//         }
//     },
//     "version": 1752564108,
//     "created_at": "2025-07-15T07:21:48.312Z"
// }
```

### Delete

Deletes a specific version of the saved data.

<figure><img src="https://4095941951-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FStEZJb1cl50eSxquMjc5%2Fuploads%2Fgit-blob-ab8b5673fdf701821849e7fd8136e160a20242ed%2Fstorage-client-cloudsave-7.png?alt=media" alt=""><figcaption></figcaption></figure>

Example code:

```
const version = 1752564108;
cloudSaveClient.delete(version, access_token);

// Possible return values:
// {
//   "message":"App data deleted successfully"
// }
// {
//   "error":"Invalid version"
// }
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.viverse.com/developer-tools/javascript/javascript-storage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.