Web Storage API

Introduction

The web storage specification, standardized by the World Wide Web Consortium (W3C), has been used to implement a permanent & semi-permanent storage of structured key-value pair data on the DSOS players.

The following APIs are available:

JavaScript API
Provides mechanisms for storing key-value pair data on the players, respectively on Elementi, using JavaScript code. Added in 3.0.0 firmware.
REST API
Provides RESTfull web services for reading and writing localStorage variables onto the player from external clients through HTTP(S) calls. Added in firmware 4.3.0.

Additionally, local storage items can also be manipulated through RPC API and Shared Variables.

JavaScript API

The JavaScript API provides two mechanisms for storing key-value pair data on the players, respectively on Elementi, using these two JavaScript global objects:

localStorage for permanent data storage, including upon player restart or publish of new content.
sessionStorage for semi-permanent storage, as the data is reinitialized following a player restart or a content publish.

Notes:

The items saved into Web Storage can also be accessed as JavaScript properties (e.g., localStorage.key). The value of an item (i.e. object property) can be read at any time, independently on the time it has been set.
Only strings can be stored in the web storage - attempting to store a different data type will result in an automatic conversion into a string. Conversion into JSON (JavaScript Object Notation), however, allows for effective storage of JavaScript objects.
When invoking the methods above, except for the getter, a storage event is fired.
The maximum size for each of the two web storage objects is 4 MB - see above how the data can be cleared.

localStorage

The localStorage object enables permanent storage of data, being resilient to player reboots. It provides access to a list of key/value pairs (sometimes called items), that can be set and / or read with the following methods:

// setter
localStorage.setItem(key, value);

// getter
localStorage.getItem(key);

// remove item
localStorage.removeItem(key);

// remove all items from the local storage
localStorage.clear();

Note:

The data stored into the web storage of the players can also be cleared from Control Center → Operations → Reset page.

sessionStorage

The sessionStorage object is identical to the localStorage object, except that the data is reinitialized whenever the content restarts, following a player reboot or a content publishing. It provides access to a list of key-value pairs (sometimes called items), that can be set and/or read with the following methods:

// setter
sessionStorage.setItem(key, value);

// getter
sessionStorage.getItem(key);

// remove item
sessionStorage.removeItem(key);

// remove all items from the session storage
sessionStorage.clear();

REST API

Applies to all DSOS players with DSOS SYSTEMS license, except for HMP300 and DiVA.

The Web Storage REST API allows manipulating the localStorage data of the player from external clients through HTTP(S) calls. REST stands for "Representational State Transfer", which is a software architectural style that defines a set of constraints to be used for creating web services. It was added in firmware 4.3.0.

The following operations are supported:

List the existing keys
Get the value of a key
Set the value of one or more keys
Delete a key

Configuration

APIs Security settings

The REST API is deactivated by default – follow these steps to activated it:

Open Control Center → Advanced Applications → API Security page.
Activate "Enable security token access to the Webstorage API" option.
If the script calling this API is not running on the player content server and the requests are being blocked due to CORS, then activate the "Enable CORS requests" option as well.
If needed, replace the generated security token and API key with your own.
Click the "Apply" button.

Authentication

To access the API end-points, the security token, generated and stored on the player, must be provided with each call, through a "Bearer Authorization" header or an "access_token" query string parameter. Alternatively, the authentication can be done using the credentials of users defined in user manager with content authoring or admin rights. Both TLS-SRP and HTTP Basic authentication methods are supported.

Notes:

Using HTTP is not secure, any eavesdropper can steal the bearer token or user password – using HTTPS, either with self-signed certificate or with TLS-SRP is a secure alternative.
To protect the player against CSRF when using CORS (i.e., the script is located on another host) the spx-api-key={rpcApiKey} query string parameter must be appended to the end-point, where {rpcApiKey} is the API Key configured on that player, either from Control Center → Advanced Applications → APIs Security section, or by using the <rpc-api-key> configuration tag.

Endpoint

The endpoint webstorage allows the following operations:

GEThttp(s)://player_address/webstorage

Get the list of web storage variables on the player.

GEThttp(s)://player_address/webstorage/{key} or /webstorage?name={key}

Get the value of the variable named {key}.

POSThttp(s)://player_address/webstorage

Update one of more variables using the content of a form.

POSThttp(s)://player_address/webstorage/{key} or /webstorage?name={key}

Update the variable named {key} with the content of the POST.

POSThttp(s)://player_address/webstorage/{key}?expect={value}

Update the variable named {key} with the content of the POST, only is the previous value of the variable is equal to {value}.

DELETEhttp(s)://player_address/webstorage/{key}

Delete the variable named {key}.

PURGEhttp(s)://player_address/webstorage/

Delete all the variables. Added in firmware 4.6.1.

Note:

The full documentation, including examples, can be found here: https://api.docs.spinetix.com/ .

Tool

This tool is served from a secured connection, so the browser will block a request to a player address using HTTP (default behavior when the protocol is not provided) due to mixed active content protection – the solution is to disable the browser protection on this page or enter an HTTPS player address (you need to prior install the player self-signed certificate).

Alternatively, this tool can be downloaded from our server for local usage.

Other APIs

RPC API

The RPC API offers several webstorage_*** RPC commands to interact with the data stored in the localStorage. It is especially useful for cases when the communication needs to be initialized by the player itself (typical usage is when the player is behind a firewall or a NAT) when using the native REST API would be problematic.

Shared Variables

Shared Variables are automatically saved into the localStorage object since firmware 3.1.0, thus updating a Shared Variable triggers a modification within the localStorage object as well.