sparks

The sparks plugin is responsible for fetching Sparks from the Sparks Service and dynamically inject them into the stream in predefined locations.
It provides an API that allows project’s code to tag the state of the viewer, which will be used for getting the relevant Spark in run time.

Example

// playerOptions.json
{
    "plugins": {
        "sparks": {
            "projectId": "myProjId",
            "nodes": [
                "node_before_spark1",
                "node_before_spark2"
            ],
        }
    }
}

// app.js
player.on('nodestart', function(node) {
     if (node.id === 'node_happy') {
         player.sparks.tag = 'happy';
     } else if (node.id === 'node_sad') {
         player.sparks.tag = 'sad';
     }
});

• Table of Contents
  • Init Options
    • enabledp
    • debugp
    • initialTagp
    • nodesp
    • playSparkOnSeekp
    • trackersp
    • minInteractionsToPlaySparksp
    • initialInteractionsCountp
  • Properties
    • tagp
    • versionpro
  • Methods
    • attachm
    • detachm
  • Events
    • sparks.sparkstarte
    • sparks.sparkende
    • sparks.prerequeste

Init Options

options : object

Initialization options for the sparks plugin.

• options : object
  • .enabled : boolean
  • .debug : boolean
  • .initialTag : string
  • .nodes : Array.<string> | string
  • .playSparkOnSeek : boolean
  • .trackers : Array.<string>
  • .minInteractionsToPlaySparks : number
  • .initialInteractionsCount : number

options.enabled : boolean

property

Should sparks be injected.

Default: false

options.debug : boolean

property

Debug mode. When set to true the plugin will show a debug overlay with useful information about the tags values and the plugin’s behavior.

Default: false

options.initialTag : string

property

An initial tag value to set when the plugin has been initialized.

Default: "''"

options.nodes : Array.<string> | string

property

Array of ids of sparkable nodes the plugin should attach on intialization.

Default: []
See: attach

options.playSparkOnSeek : boolean

property

Should Sparks be injected on player.seek.
playSparkOnSeek can also be configured per specific attached node by using player.sparks.attach()

Default: false
See: attach

options.trackers : Array.<string>

property

Additional third-party tracking integrations - one or multiple of [‘ias’, ‘moat’]

Default: []

options.minInteractionsToPlaySparks : number

property

The default minimum number of interactions that are required for playing a spark.
When any spark is played, the interactions count is reset back to 0.

Default: 1

options.initialInteractionsCount : number

property

The initial interactions count to set on plugin initialization.
This can affect the first spark that should play, for example:
If we decided that the fact that the user opted in to play the project counts as the first interaction then we can set this to 1.

Default: 0

Properties

player.sparks.tag : string

property

Getter and setter for the current tag.
A string representing the current state of the viewer. The plugin will use this information when fetching Sparks.

Example

player.sparks.tag = 'unknown';
player.on('nodestart', function(node) {
     if (node.id === 'node_happy') {
         player.sparks.tag = 'happy';
     } else if (node.id === 'node_sad') {
         player.sparks.tag = 'sad';
     }
});

player.sparks.version : string

propertyreadonly

The sparks plugin’s version string.

Example

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

Methods

player.sparks.attach(node, [options])

method

Define nodes as ‘sparkable’, which means that a Spark slot is attached to them. The provided nodes will be followed by a Spark.
This method accepts a node or array of nodes and an optional options object.
Make sure to call this method before pushing the node to the playlist.

NOTE: By default, a spark will be played only if there was at least 1 user interaction before reaching it. When any spark is played, the interactions count is reset back to 0.
See playSparkCondition option below for more details.

See: nodes, playSparkOnSeek

Param	Type	Description
node	string | Node | Array.<string> | Array.<Node>	The node (or node id) or array of nodes (or nodes ids) to be attached as ‘sparkable’ nodes.
[options]	object	Optional. An options object. If given it will be referred to all the nodes that were given in the first argument.
[options.tag]	string	Optional. If a value was given, it will force the tag state to this value before requesting a spark from this attached node.
[options.placement]	string	Optional. The id of the placement of this particular spark within a project (e.g. placement1)
[options.playSparkOnSeek]	boolean	Optional. If a value was given it will override the value of the plugin initialization option playSparkOnSeek for the specific nodes. If true and player.seek function was executed during the attached node, first the spark will be played and then seek to the desired node. If false, the spark won’t be played and it immediately seek to the desired node.
[options.playSparkCondition]	boolean | object	Optional. Condition for which this spark should play. - If the value is a boolean, “true” indicates to always play the spark and “false” indicates that this spark will not play. - If the value is an object, it must be as following: { type: 'interactions', min: 3 } where “min” can be any number indicating the minimum interactions required in order to play this spark, see interaction’s report method. - Default is: { type: 'interactions'} with the minimum value set by minInteractionsToPlaySparks.
[options.noTransitionIn]	boolean	Optional. If a value was given and set to true, the spark after the specific nodes won’t have a transition in.
[options.noTransitionOut]	boolean	Optional. If a value was given and set to true, the spark after the specific nodes won’t have a transition out.

Example

player.sparks.attach(['node_b1', 'node_b2'], { playSparkOnSeek: true });

player.sparks.detach(node)

method

Detach a Spark slot from the provided nodes.
This method accepts a node or array of nodes.

Param	Type	Description
node	string | Node | Array.<string> | Array.<Node>	The node (or node id) or array of nodes (or nodes ids) to be detached.

Example

player.sparks.detach(['node_b1', 'node_b2']);

Events

“sparks.sparkstart”

event

Triggered when a spark starts playing (the first node of the spark).

Example

player.on('sparks.sparkstart', function() {
    console.log('Spark is playling!');
});

“sparks.sparkend”

event

Triggered when a spark ended (the last node of the spark).

Example

player.on('sparks.sparkend', function() {
    console.log('Spark ended!');
});

“sparks.prerequest”

event

Triggered just before a spark is requested, providing an opportunity to set player.sparks.tag before the request goes out.

Param	Type	Description
node	Node	The attached node the spark will be requested from.
attachedNodeOptions	object	A copy of the options object provided when the node was attached using attach.

Example

player.on('sparks.prerequest', function(node, attachedNodeOptions) {
    // 0.5 is some threshold for overriding the tag
    if (player.variables.someVariable >= 0.5) {
        player.sparks.tag = 'tagIfAboveThreshold';
    }
});