decision

The decision plugin provides an easy-to-use api to handle the natural flow of interactive video.
Natural flow means that during an interactive video, we expect each node to push a child node to the playlist.
When this is a result of a user interaction, the decision has been made;
When no user interaction has taken place, this child node should have been automatically pushed.

Every time a decision is added, an instance of DecisionInstance is associated with the parent node.

The plugin also triggers decision.start and decision.end events that may be used by others to convey a notion of a decision interval.

To use the plugin, a player.decision.add() call must be made, passing the node afterwhich a decision should be taken.
Other options may be passed when initializing the plugin or at a later stage by simply modifying a property on the player.decision object itself.
Finally, any options passed to the add function (e.g. a decider function or the prefetch flag) will override any globally set options.
Options may also be passed on the node.data.decision object.

Init Options

options : object

Initialization options for the decision plugin.

options.checkpoints : object
property

Default configuration having to do with the checkpoints plugin.
These configuration options only take effect if the checkpoints plugin has been loaded/initialized.

options.checkpoints.enabled : boolean
property

If true, a checkpoint will automatically be registered a few seconds prior to every decision.start.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "checkpoints": {
                "enabled": false
            }
        }
    }
}
options.checkpoints.singleChild : boolean
property

If true, will automatically register checkpoints for decisions with a single child.
Only applies if options.checkpoints.enabled is set to true.

Default: false
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "checkpoints": {
                "singleChild": true
            }
        }
    }
}
options.checkpoints.time : boolean
property

The time (in seconds relative to the decision’s startTime) when a checkpoint will automatically be saved.
The requested time could also be a negative number.
Note that time will be clamped to the duration of the decision’s parent node (value will be between 0 and node’s duration).
Only applies if options.checkpoints.enabled is set to true.

Default: -5
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "checkpoints": {
                "time": -2
            }
        }
    }
}

options.prefetch : boolean
property

Initial value for the prefetch property.

Default: true
See: prefetch
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "prefetch": false
        }
    }
}

options.autoPushSingleChild : boolean
property

Initial value for the autoPushSingleChild property.

Default: true
See: autoPushSingleChild
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "autoPushSingleChild": false
        }
    }
}

options.decider : decider
property

Initial value for the decider property.

Default: The default decider.
See: decider
Example

player.initPlugin('decision', {
    decider: function(parent, children, options) {
        var candidates = (options.defaults || children);

        // If we have children/defaults, return a random node
        if (candidates && candidates.length) {
            return candidates[Math.floor(Math.random() * candidates.length)];
        }

        // Otherwise, do not push anything to the playlist
        return false;
    }
});

options.includeInCheckpoints : boolean
property

The default includeInCheckpoints value applied to each decision. See add for details.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "decision": {
            "includeInCheckpoints": false
        }
    }
}

Properties

player.decision.prefetch : boolean
property

If true, when adding a decision, will ensure that the children are present on the prefetch array of the parent node.

Default: true
See: node.addPrefetch()
Example

player.decision.prefetch = false;
player.decision.add('question', ['toBe', 'notToBe']); // 'toBe' and 'notToBe' won't be added to the prefetch array on 'question'.

player.decision.autoPushSingleChild : boolean
property

If true, when pushing a parent node with a single child to the playlist, plugin will automatically push the child to the playlist.
If the parent node has a defaults array and it’s empty or if a custom decider is set, this functionality is disabled.

Default: true
Example

player.decision.autoPushSingleChild = true;
player.decision.add('question', ['toBe']); // Node with a single child.
player.playlist.push('question'); // On the next event-loop, 'toBe' will be pushed to the playlist as well.

player.decision.decider : decider
property

If specified, will be called when the next node needs to be decided.
Note that setting this will disable the autoPushSingleChild functionality.

When adding decisions to your nodes it is highly recommended to manage your decision logic on the DecisionInstance decider function. Use of the global decider is intended for specific cases in which you want to introduce logic that affects implicit decisions across all decision instances in the project.

Functions cannot be saved/restored via checkpoints. For more info, refer to checkpoints.

Default: The default decider.
Example

// Adding 2 decisions.
player.decision.add('question1', ['toBe', 'notToBe']);
player.decision.add('question2', ['toBe', 'notToBe']);

// Define a global decider.
// On Sundays, will choose the 'toBe' node.
// On other days, will fallback to the default behavior.
player.decision.decider = function(parent, children, options) {
    // If today's Sunday, let's push the 'toBe' node
    if ((new Date()).getDay() === 0) {
        return 'toBe';
    }

    // Otherwise, let's fallback to the default decider (which will randomize between the children)
    return undefined;
}

player.decision.version : string
propertyreadonly

The decision plugin’s version string.

Example

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

Methods

player.decision.add(parent, [children], [options]) ⇒ DecisionInstance
method

Add/attach a decision to a node.
By default, upon a node’s decision endTime, the plugin will randomly push the next node from the children array.
For more advanced scenarios, see the options argument.
All options (including children) may be specified as properties on the parent node’s data.decision object.
Options passed on the options argument take precedence over options passed via the data.decision object.
If a node already has already had add() called on it (and thus a DecisionInstance already exists), this is effectively a call to update.

Returns: DecisionInstance - The newly created DecisionInstance instance now associated with that parent node.

Param Type Description
parent string | Node Required. The node (or node id) in which a decision should be made.
[children] string | Node | Array.<string> | Array.<Node> Optional. An array of nodes or node ids that are considered as candidates to be played after the parent.
[options] object Optional. An options object.
[options.startTime] number Default 0. The time (in seconds) into the parent node when decision.start event should be triggered.
[options.endTime] number The time (in seconds) into the parent node when decision.end event should be triggered. A decision should be made by then. The default value is as late as possible, ranging from 1.5 - 2.0 seconds prior to end of node (depending on the video playback engine).
[options.defaults] Array.<string> | Array.<Node> Array of nodes or node ids. If specified, the next node will be a random selection from this array.
[options.decider] decider If specified, will be called when the next node needs to be decided. NOTE: Functions cannot be saved/restored via checkpoints. For more info, refer to checkpoints.
[options.prefetch] boolean Default true. If true, will ensure that the children are present on the prefetch array of the parent.
[options.includeInCheckpoints] boolean Default true. If set to false, the state of the decision will not be saved or restored on checkpoints events.
[options.children] string | Node | Array.<string> | Array.<Node> Same as the children argument. Can be specified as part of the options object and will take precedence over the children argument specified as a separate argument.
[options.checkpoints] object An optional checkpoints config object. Overrides options.checkpoints for this decision. These options only take effect if the checkpoints plugin has been loaded/initialized.
[options.checkpoints.enabled] boolean Default true. See options.checkpoints.enabled.
[options.checkpoints.singleChild] boolean Default false. See options.checkpoints.singleChild.
[options.checkpoints.time] boolean Default -5. See options.checkpoints.time.

Example

// When 'question' node ends, will randomly select from 'toBe'/'notToBe'.
player.decision.add('question', ['toBe', 'notToBe']);

// Equivalent code:
var questionNode = player.repository.add({
    id: 'question',
    source: ...
    data: {
        decision: {
            children: ['toBe', 'notToBe']
        }
    }
});

// Will use the data.decision object for input arguments and override the prefetch flag.
player.decision.add(questionNode, {prefetch: false});

// Will exclude 'end' node from the random selection.
player.decision.add('question', ['toBe', 'notToBe', 'end'], {
    defaults: ['toBe', 'notToBe']
});

// 4 seconds before the 'todayIs' node ends - decide the next node according to the current day of the week.
player.decision.add('todayIs', {
    children: ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'], // children may also be specified under 'options'.
    endTime: -4,
    decider: function(parent, children, options) {
        var currentDay = (new Date()).getDay();
        return children[currentDay];
    }
});

player.decision.update(parent, [children], [options]) ⇒ DecisionInstance
method

Update a decision with new children and/or options.
The new options object will be merged with previous options object.
If the decision does not exist, it’ll simply invoke the add method (they share the exact same signature).

Returns: DecisionInstance - The newly updated DecisionInstance associated with that parent node. This is the same instance that was returned by the original .add() call.

Param Type Description
parent string | Node Required. The node (or node id) to update the decision of.
[children] string | Node | Array.<string> | Array.<Node> Optional. An array of nodes or node ids that are considered as candidates to be played after the parent.
[options] object Optional. An options object. Same as add options.

Example

player.decision.update('todayIs', {
    // Override just the decider function
    // Choose tommorow instead of today, just to mess with everyone's head
    decider: function(parent, children, options) {
        var currentDay = (new Date()).getDay();
        return children[++currentDay % 7];
    }
});

player.decision.get(parent) ⇒ DecisionInstance
method

Get the DecisionInstance associated with the parent node.
Supports the special value all, which will return all the decisions.
For the API of the returned object, see the DecisionInstance docs.

Returns: DecisionInstance - The DecisionInstance associated with that parent node. This is the same instance that was returned by the original .add() call.

Param Type Description
parent string | Node Required. The node (or node id) to update the decision of.

Example

var decision = player.decision.get('someNodeName');
decision.on('start', function(decision) { console.log('DecisionInstance started for node', decision.parent.id); });
decision.on('made', function(decision) { console.log('Decision has been made for node', decision.parent.id, '-', decision.selected.node.id, 'was selected!'); });

player.decision.remove(parent) ⇒ Node
method

Remove a decision from a node.

Returns: Node - The node from which a decision was removed.

Param Type Description
parent string | Node A node (or node id) that was previously added as a parent using add.

Example

// Following the examples from add(), will no longer apply any logic when 'question' ends.
player.decision.remove('question');
console.log(player.decision.data('question')); // Outputs empty object.

player.decision.data(node) ⇒ object
method

Gets a (shallow) clone of the data that the plugin associates with a node.

Returns: object - An object with the associated data.

Param Type Description
node string | Node Node or node id.

Example

console.log(player.decision.data('question').children)); // [toBe, notToBe]
console.log(player.decision.data('question').startTime)); // 0
console.log(player.decision.data('question').endTime)); // -4

Events

“decision.start”
event

Triggered when playback reaches a decision start time.
This event is also triggered on the node itself.

Param Type Description
node Node The currently playing node.

Example

player.on('decision.start', function(node) {
    showDecisionButtonsForNode(node);
});

“decision.end”
event

Triggered when playback reaches a decision end time.
This event is also triggered on the node itself.

Param Type Description
node Node The currently playing node.

Example

player.on('decision.end', function(node) {
    hideDecisionButtonsForNode(node);
});

“decision.autopush”
event

Triggered when a node is pushed to the playlist by the decision plugin.

Param Type Description
node Node The node that was pushed.
playlistIndex number The playlist index of the node that was pushed (0 based).

Example

player.on('decision.autopush', function(node, playlistIndex) {
    console.log('The \'' + node.id + '\' node was auto pushed by decision plugin to playlist at index ' + playlistIndex);
});

“decision.updated”
event

Triggered when decision data of a node was updated by calling the update function.
This event is also triggered on the node itself.

Param Type Description
node Node The node that it’s decision data was updated.

Example

player.on('decision.updated', function(node) {
    console.log('The new decision data of \'' + node.id + '\' node is', player.decision.data(node));
});

Objects

reduxState : object
property

Decision plugin’s redux state sub-object (i.e. player.reduxStore.getState().decision).

See: reduxStore
Example

// player.reduxStore.getState().decision
{
    // Decision ID (same as parent node ID)
    myParentNodeId: {

        // ID of parent node
        parent: 'myParentNodeId',

        // Array of IDs for children
        children: ['myFirstChild', 'mySecondChild'],

        // Array of IDs for default children
        defaults: ['myFirstChild'],

        // One of 'inactive', 'active' or 'made'
        state: 'made',

        // Current time within decision (in seconds)
        time: 3.333,

        // Decision's total duration (in seconds)
        duration: 10,

        // Current time within decision, normalized to range [0, 1]
        progress: 0.333,

        // Remaining decision time (in seconds)
        remainingTime: 6.667,

        // Will be an empty object if decision not yet made
        selected: {
            // The ID of selected child node
            node: 'mySecondChild',

            // Boolean. Was this auto-decided by decision plugin?
            autoDecided: false,

            // Boolean. True if decision.make() called with options.seek set to true.
            seek: false,

            // Time into the decision when the decision was made (in seconds)
            selectionTime: 2.5
        }
    }
}

Callbacks

decider ⇒ string | Node | boolean | undefined
callback

A callback function that will be invoked when a decision needs to be made.
NOTE: Functions cannot be saved/restored via checkpoints. For more info, refer to checkpoints.

Returns: string | Node | boolean | undefined - The return value will be treated as following:

  • Returning a Node (or a string node id) will result in pushing that node to the playlist.
  • Returning false will prevent the decision plugin from pushing a node to the playlist.
  • Returning undefined will fallback to the default decider function implemented in the plugin.
Param Type Description
parent Node The parent node (same node that this decision is attached to).
children Array.<Node> An array of children.
options object The options object associated with this decision.

Example

function deciderCallback(parent, children, options) {
    var candidates = (options.defaults || children);

    // If we have children/defaults, return a random node
    if (candidates && candidates.length) {
        return candidates[Math.floor(Math.random() * candidates.length)];
    }

    // Otherwise, do not push anything to the playlist
    return false;
}
Rate this page: X
Tell us more!