Shared Storage

Shared storage in embedded Experiences

The SDK provides a shared storage API that allows Experiences to access data storage located on your application. By default, storage is persistent, meaning data will be stored in the local storage of your webpage for JavaScript, or the application's sandbox for Android and iOS, ensuring data is available across multiple sessions.

It is important to note that persistent storage is enabled by default, and the use of persistent storage may be subject to laws and regulations, such as those related to data privacy and protection. You have the responsibility to ensure compliance with all regulations required for the countries and regions you operate in.

The Experience won't request the user permission to store data; instead we expect you to disable persistent storage if you need to store data only in memory for the current session, or if persistent storage does not comply with your requirements or applicable regulations.

If you need to store data only in memory (which provides faster access but will not be available across multiple sessions), you can disable persistent storage by calling setStoragePersistent(false).

API

The storage-kit provides a comprehensive API for managing storage operations:

import {
  setStoragePersistent,
  storageRead,
  storageWrite,
  storageRemove,
  storageClear,
  StorageError,
} from "@monterosa/sdk-storage-kit";

// Persistent storage is enabled by default
// To disable persistent storage (store in memory only):
setStoragePersistent(false);

// To explicitly enable persistent storage:
setStoragePersistent(true);

// Read a value from storage
const value = await storageRead('myKey');

// Write a value to storage
await storageWrite('myKey', 'myValue');

// Remove a specific item from storage
await storageRemove('myKey');

// Clear all storage data
await storageClear();

All storage operations (storageRead, storageWrite, storageRemove, storageClear) are asynchronous and return Promises. They will automatically use the parent application's storage when the Experience is embedded, or fall back to local storage/memory when running standalone.

Error handling

The storage functions can throw errors, which can be identified using the StorageError enum:

import { storageRead, StorageError } from "@monterosa/sdk-storage-kit";

try {
  const value = await storageRead('myKey');
} catch (error) {
  if (error.code === StorageError.ReadError) {
    // Handle read error
  } else if (error.code === StorageError.ParentAppError) {
    // Handle parent application error
  }
}

Available error codes:

• StorageError.ParentAppError - An error occurred in the parent application

• StorageError.ReadError - An error occurred when reading from storage

• StorageError.WriteError - An error occurred when writing to storage

• StorageError.RemoveError - An error occurred when removing from storage

• StorageError.ClearError - An error occurred when clearing storage

Storage Persistence

The SDK ensures that data is transitioned seamlessly from persistent to in-memory and back by copying the data available from memory to disk, and the other way around, so any change in configuration won't result in any data loss during your user's session.

When switching from in-memory to persistent storage, all data currently in memory will be copied to persistent storage. When switching from persistent to in-memory storage, the persistent storage will be cleared (data remains available in memory for the current session).

The persistence setting persists across sessions—if you set it to true, it will remain true in subsequent sessions, and if you set it to false, it will remain false.