Using Data Storage in Custom Widgets

Custom widgets in StreamerCatalyst can access and persist data through two primary methods: the SC_API (SC runtime) and the SE_API (StreamElements compatibility layer).

Per-Widget Storage (SC_API)

The SC_API provides per-widget key-value storage. This data is local to the specific widget instance. This storage is subject to the following limits:

• Maximum value size: 8 KB per value
• Maximum keys: 100 keys per widget
• Total storage capacity: 100 KB per widget

StreamElements Compatibility (SE_API)

If you are migrating a widget from StreamElements or prefer its syntax, you can use the SE_API compatibility layer.

Key-Value Store

The SE_API provides store.get and store.set methods for managing data in a StreamElements-style way.

Counters and Metrics

You can retrieve channel-wide data using counters.get. The way you name the argument determines what data is returned:

• Chatters Counters: Use a bare name to retrieve a specific chatter counter. These names must be lowercase and can include a-z, 0-9, and _ (up to 32 characters). For example, deaths is a valid bare name for a counter.
• Module Metrics: Use dotted notation to retrieve metrics from specific modules. Examples include numbers.follows, rewards.total_bits, or chatters.regulars_count.

[!CAUTION] Do not combine these formats. For example, calling chatters.deaths will result in an error because deaths is a counter and must be called as a bare name.

Session Data

For imported widgets, session.data is available within the onWidgetLoad detail. This allows imported goal or counter widgets to resume their running totals from real history rather than restarting at zero when the overlay is reloaded.

Example Code

The following example demonstrates how to use the SE_API to retrieve a counter, a module metric, and use the store for custom data.

// 1. Retrieving a channel-wide Chatters counter
// Use a bare name (lowercase, a-z, 0-9, _)
const deathCount = SE_API.counters.get('deaths');

// 2. Retrieving a module metric
// Use dotted notation for module-specific data
const followCount = SE_API.counters.get('numbers.follows');

// 3. Using the SE_API store for custom key-value data
SE_API.store.set('last_event_type', 'sub');
const lastEvent = SE_API.store.get('last_event_type');

// Example of handling the session data on load (for imported widgets)
// This data is part of the onWidgetLoad detail
function handleWidgetLoad(event) {
  if (event.session && event.session.data) {
    const currentGoal = event.session.data;
    console.log("Resuming from session data:", currentGoal);
  }
}