eko-js-sdk
A lightweight SDK that allows for easy integration of eko videos into webpages
Installation
From your favorite CLI tool:
npm install @ekolabs/eko-js-sdkAPI
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');
}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(id, options)
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 |
|---|---|---|
| id | String |
The eko video id 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 completes, the eko-player-loading class will be removed and replaced with eko-player-loaded. Once video begins playback, the eko-player-loaded class will be removed and replaced by eko-player-started. If a function is passed, it will be invoked with a string argument (state) whenever the state changes. Some states may also include a 2nd object argument which contains properties pertaining to the state. The possible state values are loading (cover should be shown), loaded (cover should be hidden and play button shown) and started (both cover and play button should be hidden). If no cover is provided, the default eko loading cover will be shown. |
| options.iframeAttributes | Object |
standard attributes of iframe HTML element. |
| options.excludePropagatedParams | String[] |
By default, all query string params present on the page will be forwarded onto the video iframe. In order to exclude params from being forwarded, you can supply an array of query param keys (strings or regexes) to list the params that should not be propagated. |
Example
let ekoPlayer = new EkoPlayer('#myContainer', '1.0');
ekoPlayer.load('AWLLK1', {
params: {
autoplay: false,
clearcheckpoints: true,
debug: true
},
events: ['nodestart', 'nodeend', 'playing', 'pause'],
cover: '#myCoverId',
iframeAttributes: { title: 'My Eko Player' }
});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 myNodeIdThe 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)
dispose()
Will dispose EkoPlayer instance
Example
const ekoPlayer = new EkoPlayer('#myContainer');
ekoPlayer.dispose();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.intentshare.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']
});