Embed API

Eko provides a set of APIs to support developers who want a deeper integration of eko projects into their products. The embed API allows developers to control eko projects by listening to messages from the iframe element and posting messages into the iframe element.

It’s assumed that you are already familiar with the embedding options explained in Embedding in Web Pages.

To enable the API the following parameters should be added to the embed URL:

Param Description
embedapi Embed API version. Must be set to 1.0.
embedid A unique id of the iframe. Default is ekoembed.
events Optional. Comma-separated list of events. See Custom Events for details.

The following snippet embeds the first episode of That Moment When with the API enabled:

<div style="position: relative; padding-bottom: 56.25%; height: 0; max-width: 100%;">
    <iframe 
        id="ekoproject" 
        title="That Moment When"
        src="https://eko.com/tmw/101/embed?embedapi=1.0&embedid=myproject" 
        style="width: 100%; height: 100%; border: 0;" 
        allowfullscreen 
        allow="autoplay; fullscreen">
    </iframe>
</div>



Core Events

When the API is enabled, the iframe triggers events via postMessage. By adding an event listener for message on the window, one can handle messages from the iframe. Messages include the following parameters:

Param Type Description
type string Event type
embedApiVersion string API version provided in the embedapi param
embedId string The embed ID provided in the embedid param

The following example provides a skeleton for such a listener:

window.addEventListener('message', (event) => {
    if (!/https?:\/\/(.*?\.)?eko.com/.test(event.origin)) {
        return;
    }

    const msg = event.data;
    switch (msg.type) {
        case 'eko.canplay':
            // Handle message
            break;
        case 'eko.playing':
            // Handle message
            break;
        case 'eko.pause':
            // Handle message
            break;
        case 'eko.exit':
            // Handle message
            break;
        case 'eko.error':
            // Handle message
            break;
        case 'eko.forcelandscape':
        // Handle message
        break;
        default:
            break;
    }
});


eko.canplay

Triggered when player has buffered enough media to begin playback.

Param Type Description
type string eko.canplay
embedApiVersion string API version
embedId string iframe ID

eko.playing

Triggered when the media begins to play (either for the first time, after having been paused/waiting, or after restarting).

Param Type Description
type string eko.playing
embedApiVersion string API version
embedId string iframe ID

eko.pause

Triggered when playback is paused.

Param Type Description
type string eko.pause
embedApiVersion string API version
embedId string iframe ID

eko.exit

Triggered when user clicks the exit/back button.

Param Type Description
type string eko.exit
embedApiVersion string API version
embedId string iframe ID

eko.error

Triggered when an error occurred.

Param Type Description
type string eko.error
embedApiVersion string API version
embedId string iframe ID
data object Error object
data.code number Error code
data.message string Error message

eko.forcelandscape

Triggered when the project runs on an Instagram webview and requests to be viewed in landscape. Can be achieved via CSS manipulations on the iframe.

Param Type Description
type string eko.error
embedApiVersion string API version
embedId string iframe ID
data object Error object
data.code number Error code
data.message string Error message

Custom Events

In some cases the default events triggered from the iframe are not sufficient. Developers can ask for additional events to be triggered by adding the events query param to the iframe’s src url. It’s a comma-separated list of additional events that will be posted from the iframe.

Those events have the following fields:

Param Type Description
type string The event name prefixed with eko. (e.g. eko.nodestart)
embedApiVersion string API version
embedId string iframe ID
args array An array of the params sent with the event. See the API documentation of the event for details.

Projects can use the events mechanism to implement custom events. One can call player.trigger with a custom event name and arguments. If you want those events to be posted via the embed API to the embedding page, make sure the arguments sent with the event are JSON.stringify friendly.

For example, let’s assume you want to change some button text if users got to a specific node within the project and update some element with the value of a variable called score. You can listen to nodestart and variables.update by embedding the following url:

https://eko.com/v/my-proj/embed?embedapi=1.0&embedid=myproj&events=nodestart,variables.update

The following code snippet handles the DOM changes upon receiving events from the iframe:

window.addEventListener('message', (event) => {
    if (!/https?:\/\/(.*?\.)?eko.com/.test(event.origin)) {
        return;
    }

    const msg = event.data;
    switch (msg.type) {
        case 'eko.nodestart':
            const node = msg.args[0];
            if (node.id === 'node_learn_more') {
                document.querySelector('button[name="cta"]').innerText = 'Learn More';
            }
            break;
        case 'eko.variables.update':
            const name = msg.args[0];
            const oldValue = msg.args[1];
            const newValue = msg.args[2];
            if (name === 'score') {
                document.querySelector('#score').innerHtml = newValue;
            }   
            break;
        default:
            break;
    }
});



Actions

Actions allow executing eko API calls from the page which embeds the content, by posting messages to the iframe via its contentWindow.postMessage method.
The embed API must be enabled The following table describes the structure of the messages:

Param Type Description
type string The eko API method. It should have an eko prefix instead of player. The embed API will locate the player instance wihthin the iframe. For example player.audio.play should be written as eko.audio.play
args array An array of arguments that will be provided to the eko API method.

The args array is serialized using the structured clone algorithm. This means that functions cannot be sent. type cannot be one which expectes to receive a function as an argument, such as player.on.

The following examples put it all together:

// send an action to play
const playPlayAction = { 
    type: 'eko.play',
    args: []
}
document.getElementById('ekoproject')
    .contentWindow.postMessage(playPlayAction, '*');


// send an action tp play an audio asset with the id `ping`
const playPlayAudioAction = {
    type: 'eko.audio.play',
    args: [ 'ping' ]
}
document.getElementById('ekoproject')
    .contentWindow.postMessage(playPlayAudioAction, '*');


// send an action to seek to an offset of 10 seconds in 'myNodeId'
const seekAction = {
    type: 'eko.seek',
    args: [ 'myNodeId', 10 ]
}
document.getElementById('ekoproject')
    .contentWindow.postMessage(seekAction, '*');

If the eko API method does not require args a string can be provided instead of an object:

document.getElementById('ekoproject')
    .contentWindow.postMessage('eko.play', '*');
Rate this page: X
Tell us more!