# Storage SDK

***

> **BEFORE GETTING STARTED:** you must [authenticate with VIVERSE](https://docs.viverse.com/developer-tools/login-and-authentication-for-the-sdk), 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.

```
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"
// }
```