Storage Scopes

The SDK provides four storage scopes that control how data is shared across the fleet. Each scope determines who can see the data: every device, one playlist placement, a single device, or applications that opt into a shared namespace.

The Four Scopes

Application Storage

Application storage is global — data written here is available to every instance of the application on every device. Use it for shared configuration that applies everywhere, like a company logo URL or a global announcement.

// Write from any component
await store().application.set('companyLogo', 'https://example.com/logo.png');

// Read from any component, on any device
const logo = await store().application.get<string>('companyLogo');

Instance Storage

Instance storage is scoped to a specific placement of the application in a playlist. When the same weather application is placed on two different playlists showing different cities, each instance has its own storage. Settings views write to instance storage by default, making it the most commonly used scope.

// Settings view writes city for this specific placement
await store().instance.set('city', 'New York');

// Render view on the device reads the same instance
const city = await store().instance.get<string>('city');

Device Storage

Device storage persists data on a single physical device. It survives application updates and playlist changes but doesn't sync to other devices. Use it for local calibration data, cached credentials, or hardware-specific configuration.

// Cache data locally on this device
await store().device.set('cachedWeather', { temp: 72, timestamp: Date.now() });

// Available after restarts, not synced to other devices
const cached = await store().device.get<{ temp: number; timestamp: number }>('cachedWeather');

warning Device storage is only available in the Render mount point. Using it in Settings or Web views will throw an error.

Shared Storage

Shared storage enables communication between different applications running on the same device. Applications opt into a shared namespace, allowing a data-collection application to publish information that a display application consumes without tight coupling.

// App A publishes to a shared namespace
await store().shared('sensor-data').set('temperature', 72.5);

// App B reads from the same namespace
const temp = await store().shared('sensor-data').get<number>('temperature');

Scope Comparison

Real-Time Subscriptions

Changes to storage propagate in real time. When a settings view updates a value, the render view on the device receives the change within seconds through subscription callbacks:

// Subscribe to changes
store().instance.subscribe('city', (newCity: string) => {
  updateDisplay(newCity);
});

// Unsubscribe when done
store().instance.unsubscribe('city', handler);

Choosing a Scope

• Most settings → instance (per-placement configuration)
• Global config → application (shared across all instances)
• Local cache → device (device-specific, not synced)
• Cross-app data → shared(namespace) (inter-application communication)

For the complete storage API, see Storage Methods. For React hooks that simplify storage access, see React Hooks.