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:

  • embedapi=1.0
  • embedid=myid. myid is a unique id of the iframe.

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://helloeko.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
[data] object Optional. Additional fields according to the event type

The following example provides a skeleton for such a listener:

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

    let 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;
        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



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://helloeko.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://helloeko.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://helloeko.com/v/101",
    "duration": 420
}


Playlists

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

https://helloeko.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://helloeko.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://helloeko.com/tmw/"
}
Rate this page: X
Tell us more!