---
name: "SmartStorageAbility"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "Usage"
summary: "SDM storage capability guide for local and cloud synced key-value data."
---

# Usage

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Device Support</span>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Support</span>
</div>

<Callout type="info" emoji="ℹ️">
Current storage capacity sdk abstracts the following capabilities:
- key prefix: Automatically prefixes storage keys with dev id values to prevent data conflicts caused by storage on different devices of the same product.
- Data Auto-Synchronization: When developers manipulate custom data, it is automatically stored both locally (using getStorage/setStorage) and in the cloud (using getDevProperty/saveDevProperty), ensuring synchronization between the two. The system always returns the latest data, preventing data loss in weak network environments by ensuring local operations are synchronized with the cloud.
</Callout>

## SmartStorageAbility

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 Use after mounting via SmartDeviceModel abilities configuration.
> Supports both single devices and device groups.

### Description

Smart storage capability that provides cloud-persistent, device-level key-value storage

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | `DeviceId \| Object` | No | Storage capability initialization configuration |

##### SmartStorageAbility.options properties

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `deviceId` | `string` | No | - |  |
| `groupId` | `string` | No | - |  |
| `storageType` | `"local" \| "cloud" \| "both"` | No | - |  |


### Return Value

Type: `SmartStorageAbility`

SmartStorageAbility instance

#### Methods

| Method | Description |
| --- | --- |
| `init` | Initialize the storage capability and establish cloud and local storage channels |
| `get` | Read the stored data for the specified key |
| `getAll` | Read all stored data under the current device/group |
| `set` | Store data for the specified key |
| `setAll` | Batch store multiple key-value pairs |
| `remove` | Delete the stored data for the specified key |

### Referenced Types

##### `type` DeviceId

```typescript
export type DeviceId = string;
```


### Examples

#### Example

```typescript
import { SmartDeviceModel, SmartStorageAbility } from '@ray-js/panel-sdk';

const sdm = new SmartDeviceModel({ abilities: [new SmartStorageAbility()] });
```