storage

The storage plugin lets you use persistent storages for writing and reading data across the users viewing sessions.
The data availability scope can be per episode or per the entire series (for a show with multiple episodes).

Storage Scope
In order to have storage data available across all episodes, they need to be grouped under a playlist. To have them grouped, reach out to your contact person at eko.

Storage Session
Storage data is stored on the browser’s persistent storage. This means the data will only be available on the same device and browser (excluding anonymous browsing).

A note regarding Checkpoints:
The checkpoints plugin makes use of the storage plugin to function. In order for it to fucnction properly, do not modify any storage data related to it.

IMPORTANT CAVEAT:
By default, storage data is not saved persistently when in preview or when using eko-cli ‘studio test’ command.

To enable persistent storage when using eko-cli, add the --enablestorage flag.
For example: eko studio test --enablestorage.

If you require to use a ‘series’ scope storage, you should add an additional --showid flag.
For example: eko studio test --enablestorage --showid=myshow

NOTE: Enabling the storage will enable all storage related features (like checkpoints, …).
NOTE: Clearing the storage that has been saved persistently can be done in the storage debug tab.

Access to a storage is done by using a storageProxy object which is received by calling the get method.

Example

// On the first episode of the series:
player.storage.get('myStorageId', { scope: 'series' })
    .then(function(storageProxy) {
         storageProxy.setItem('watchedEpisode1', true);
     })
     .catch(function(err) { console.log('Error attempting to get storage...', err); });

// On the second episode of the series:
player.storage.get('myStorageId', { scope: 'series' })
    .then(function(storageProxy) {
         var watchedEpisode1 = storageProxy.getItem('watchedEpisode1');
         console.log(watchedEpisode1); // true
     })
     .catch(function(err) { console.log('Error attempting to get storage...', err); });

• Table of Contents
  • Properties
    • versionpro
  • Methods
    • getm

Properties

player.storage.version : string

propertyreadonly

The storage plugin’s version string.

Example

console.log('The storage plugin version is', player.storage.version);

Methods

player.storage.get(storageId, [options]) ⇒ Promise

method

Gets a storageProxy object for working with a storage.

Returns: Promise - A Promise which resolved with the created storageProxy.

Param	Type	Description
storageId	string	Your unique id to identify this storage and use it for later sessions. This allows creation of multiple non conflicting storages.
[options]	object	An optional options object which accepts the following params:
[options.scope]	string	Optional. The availability scope of the storage. If set to 'episode', this storage is saved and available only for current episode. If set to 'series', this storage is shared for all episodes in the series (requires this episode to be part of a show). Default: 'episode'.

Example

player.storage.get('myStorageId', { scope: 'series' })
    .then(function(_storageProxy) {
         storageProxy = _storageProxy;
         storageProxy.setItem('watchedEpisode1', true);
     })
     .catch(function() { console.log('Error attempting to create storage...'); });

Objects

storageProxy : object

A proxy to an actual storage .which can be used to save or read persistent data.
The API is similar to HTML5 WebStorage.

• storageProxy : object
  • .setItem(key, value) ⇒ Promise
  • .getItem(key) ⇒ *
  • .removeItem(key) ⇒ Promise
  • .clear() ⇒ Promise
  • “storage.modified”

storageProxy.setItem(key, value) ⇒ Promise

method

When passed a key name and value, will add that key to the storage or update that key’s value if it already exists.
Similar to HTML5 WebStorage, only values that are stringable will be saved.

Although this action is reflected immediately in the storageProxy object, the actual storage database affected is usually updated asynchronously. If you wish to know when the action succeeded in the actual storage database, this method returns a promise.

Returns: Promise - resolves if the item is succesfully set and rejects otherwise.

Param	Type	Description
key	string	The variable’s key.
value	*	The variable’s value.

Example

storageProxy.setItem('ep1ColorChoice', 'blue');

storageProxy.getItem(key) ⇒ *

method

When passed a key name, will return that key’s value.

Returns: * - The variable’s current value.

Param	Type	Description
key	string	The variable’s key.

Example

var ep1ColorChoice = storageProxy.getItem('ep1ColorChoice');
console.log(ep1ColorChoice); // 'blue'

storageProxy.removeItem(key) ⇒ Promise

method

When passed a key name, will remove that key from the storage.

Although this action is reflected immediately in the storageProxy object, the actual storage database affected is usually updated asynchronously. If you wish to know when the action succeeded in the actual storage database, this method returns a promise.

Returns: Promise - resolves if the item is succesfully removed and rejects otherwise.

Param	Type	Description
key	string	The variable’s key.

Example

storageProxy.removeItem('ep1ColorChoice');

storageProxy.clear() ⇒ Promise

method

When invoked, will empty all keys out of the storage.

Although this action is reflected immediately in the storageProxy object, the actual storage database affected is usually updated asynchronously. If you wish to know when the action succeeded in the actual storage database, this method returns a promise.

Returns: Promise - resolves if storage is succesfully cleared and rejects otherwise.
Example

storageProxy.clear();

“storage.modified”

event

Triggered when the storage object has been modified.

Param	Type	Description
key	string	The storage key.
oldValue	*	The old value of the key in the storage.
newValue	*	The new value for this key in the storage.

Example

storageProxy.on('storage.modified', function(key, oldValue, newValue) {
    console.log('The ' + key + ' in storage has been updated: ' + oldValue + ' => ' + newValue);
});