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.
Our JavaScript, and mobile SDKs make it much easier to use the embed API. Consider using them instead of reading this page.
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', '*');