eko-js-sdk

eko-js-sdk

A lightweight SDK that allows for easy integration of eko videos into webpages

API

EkoPlayer

Initialize an instance of the EkoPlayer to play an eko video.

Static

isSupported()

Will return true if playing eko projects is supported in your current web browser.

Example

if (!EkoPlayer.isSupported()) {
    alert('Eko is not supported on current environment');
}

getProjectInfo(projectId)

Retrieves delivery information about the project. See our project schema documentation for more information about what is delivered.

Param	Type	Description
projectId	String	The id of the project to retrieve information for.

Example

EkoPlayer.getProjectInfo('AWLLK1')
    .then(projectInfo => {
        const { title, description, thumbnail } = projectInfo;
        console.log(`Got project info: ${title} - ${description}`);
    })
    .catch(e => console.error('Failed to fetch project info:', e));

Methods

EkoPlayer(el)

Creates an instance of an EkoPlayer.

Param	Type	Description
el	Element, String	The container element to be used by the player, or a DOM selector string for the container element.

load(projectId, options) → Promise

Will load and display an eko project. The EkoPlayerView will display the loading animation while it prepares the project for playback. Returns a promise that will fail if the project id is invalid.

Param	Type	Description
projectId	String	The id of a project to load and display.
options	Object	Options for project delivery.
options.params	Object	A dictionary of embed params that will affect the delivery. Default includes {autoplay: true}.
options.events	String[]	A list of events that should be forwarded.
options.cover	Element, string, function	An element or the query selector string for a loading cover. When loading happens a “eko-player-loading” class will be added to the element. When loading finishes, the “eko-player-loading” class will be removed. If a function is passed, it will be invoked with a single string argument (state) whenever the state changes. The possible state values are "loading" (cover should be shown) and "loaded" (cover should be hidden). If no cover is provided, the default eko loading cover will be shown.
options.frameTitle	String	The title for the iframe.
options.pageParams	String[]	Any query params from the page url that should be forwarded to the iframe. Can supply regex and strings. By default, the following query params will automatically be forwarded: autoplay, debug, utm_*, headnodeid.

Example

let ekoPlayer = new EkoPlayer('#myContainer');
ekoPlayer.load('AWLLK1', {
    params: {
        autoplay: false,
        clearcheckpoints: true,
        debug: true
    },
    events: ['nodestart', 'nodeend', 'playing', 'pause'],
    cover: '#myCoverId',
    frameTitle: 'My Eko Player',
    pageParams: ['myCustomQueryParam']
});

play()

Will play/resume eko video project.

pause()

Will pause eko video project.

invoke(method, ...args)

Will call any player function defined on the eko developer site. Can also be used to set properties.

Param	Type	Description
method	String	The player method to call.
args	Any	Any arguments that should be passed into the method (must be serializable to json)

Example

ekoPlayer.invoke('play'); // Plays the eko project
ekoPlayer.invoke('audio.play', 'ping'); // Plays the "ping" sound effect via the audio plugin
ekoPlayer.invoke('seek', 'myNodeId', 10); // Seeks 10s into myNodeId

The args array is serialized using the structured clone algorithm. This means that functions cannot be sent as args.

on(eventname, callbackFn)

The eko player triggers a number of events. The app can listen to these events by providing the event name in the load call. The callbackFn will be invoked with the arguments passed by the triggered event.

off(eventname, callbackFn)

once(eventname, callbackFn)

Default Player Events

canplay

Triggered when the player has buffered enough media to begin playback.

playing

Triggered when playback has begun.

URLs and Sharing

If you wish to handle opening urls or social sharing yourself, simply add the following events to the options in the load call:

• urls.intent
• share.intent

Example

let ekoPlayer = new EkoPlayer('#myContainer');

// Handle opening URLs in parent frame
ekoPlayer.on('urls.intent', ({ url }) => {
    window.open(url, '_blank');
});

// Must pass the 'urls.intent' event at load() time
// in order to be able to listen to this event
ekoPlayer.load('AWLLK1', {
    events: ['urls.intent']
});