Storing Extension State

Overview

MEDKit provides 5 state stores with varying scopes.

All State

All State is an aggregate of all the states

Any role can retrieve

SDK Docs: getAllState

Returns all four state stores in a single response.

sdk.getAllState().then(state => {
  console.log(state);
});

Response:

{
  "extension": {},
  "channel": {},
  "viewer": {},
  "extension_viewer": {}
}

Extension State

Extension state is shared across all instances of the extension.

Requires the broadcaster role with a user ID that matches the extension owner or admin to set.

Any role can retrieve.

SDK Docs: getExtensionState

Returns the data currently stored in the Extension level state.

sdk.getExtensionState().then(state => {
  console.log(state);
});

Response:

{
  "sample_field": "test"
}

SDK Docs: setExtensionState

Sets the data to be stored in the Extension level state.

const newState = {
  sample_field: 'test'
};

sdk.setExtensionState(newState).then(state => {
  console.log(state);
});

Response:

{}

Channel State

Channel state stores extension data on a per channel basis.

Requires the broadcaster role to set.

Any role can retrieve.

SDK Docs: getChannelState

sdk.getChannelState().then(state => {
  console.log(state);
});

Response:

{
  "sample_field": "test"
}

SDK Docs: setChannelState

const newState = {
  sample_field: 'test'
};

sdk.setChannelState(newState).then(state => {
  console.log(state);
});

Response:

{}

Viewer Extension State

Viewer Extension State stores information per user that is accessible across every instance of the extension on Twitch.

Any role can set.

Any role can retrieve.

SDK Docs: getExtensionViewerState

sdk.getExtensionViewerState().then(state => {
  console.log(state);
});

Response:

{
  "sample_field": "test"
}

SDK Docs: setExtensionViewerState

const newState = {
  sample_field: 'test'
};

sdk.setExtensionViewerState(newState).then(state => {
  console.log(state);
});

Response:

{}

Viewer Channel State

Viewer Channel State store information for a viewer on a specific channel.

Any role can set.

Any role can retrieve.

SDK Docs: getViewerState

sdk.getViewerState().then(state => {
  console.log(state);
});

Response:

{
  "sample_field": "test"
}

SDK Docs: setViewerState

const newState = {
  sample_field: 'test'
};

sdk.setViewerState(newState).then(state => {
  console.log(state);
});

Response:

{}

JSON Store

The JSON store is used similarly to the channel state, in that a broadcaster can use it to store arbitrary JSON data that is accessible to all viewers. The stored data is specific to a particular channel and cannot be accessed by viewers of a different channel.

Unlike channel state however, each channel can have several JSON stores, accessed by different keys. The data associated with each key must be under 2KB, but there is no limit to the number of keys in use.

Also, when pushing new data to the JSON store, a messenger event is automatically sent to all active viewers of the associated channel and the broadcaster’s live and config pages. This event will have the format json_store_update:${key}.

SDK Docs: getJSONStore

sdk.getJSONStore('basecamp').then(basecamp => {
  if (basecamp && basecamp.tanks) {
    deploy(basecamp.tanks);
  }
});

SDK Docs: listen

sdk.listen('json_store_update:basecamp').then(data => {
  // data.id will equal 'basecamp'
  console.log(data.value);
});