Integration API

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

It is 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 Optional. A unique id of the iframe. Default is ekoembed.
events Optional. Comma-separated list of events. See Additional 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" 
        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>



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.ended':
            // 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.ended

Triggered when the playback ended.

Param Type Description
type string eko.ended
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



Additional 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 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 speific 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 are messages that are sent to the iframe via its contentWindow.postMessage method. For example:

document.getElementById('ekoproject')
    .contentWindow.postMessage('eko.play', '*');

document.getElementById('ekoproject')
    .contentWindow.postMessage('eko.pause', '*');


eko.play

Send a play message to the iframe, which triggers a call to the player.play method.

eko.pause

Send a pause message to the iframe, which triggers a call to the player.pause method.



HTTP API

Eko’s delivery service provides public HTTP API endpoints that can be used to fetch metadata from Eko.

Projects

A project’s metadata can be fetched from the following endpoint:

https://eko.com/api/v1/projects/{projectId}

The response is a JSON object with the following fields:

Field Description
id Project’s ID
title Project’s title
description Project’s description
thumbnail Project’s thumbnail
url Project’s canonical URL
[duration] Optional. Average duration

Below is the response for https://eko.com/api/v1/projects/MebL1z

{
    "id": "MebL1z",
    "title": "#TMW You Vaguely Remember Someone Who Totally Knows You",
    "description": "Help Jill remember how she knows this guy and what his f***ing name is.",
    "thumbnail": "https://d1ux84wfod9ezj.cloudfront.net/efu/upload/b706223d6acae0a7f478f77e2eb82be7.jpg",
    "url": "https://eko.com/v/101",
    "duration": 420
}


Playlists

A playlist’s metadata can be fetched from the following endpoint:

https://eko.com/api/v1/playlists/{playlistId}

The response is a JSON object with the following fields:

Field Description
id Playlist’s ID
title Playlist’s title
type Playlist’s type
description Playlist’s description
projects An array of projects IDs
url Playlist’s canonical URL

Below is the response for https://eko.com/api/v1/playlists/TMW

{
    "id": "TMW",
    "title": "That Moment When",
    "type": "show",
    "description": "Jill is a hot mess. It's up to YOU to navigate through a series of awkward moments that either leave her somewhat dignified or even hot-messier. Starring Milana Vayntrub, and created by Sandeep Parikh.",
    "projects": [
        "MebL1z",
        "Vl7yDA",
        "MZxdDA",
        "Vkm8Zz",
        "M0q9Kz",
        "Vk2NZA",
        "V1qkGV"
    ],
    "url": "https://eko.com/tmw/"
}
Rate this page: X
Tell us more!