Loading Flow

Eko projects are applications. Loading them is complex and involves loading, initialization and execution of the project’s code and the Eko API. In addition, video, audio and images are loaded and a dynamic stream is generated. It takes time.
To provide users a great experience we don’t want them to wait for the loading to finish. Eko uses a lazy loading process that is optimized for starting the video playback as soon as possible.
This guide will help you understand how this process works and how to optimize your project to make the most out of it.

The Intro

The intro is the part of the project that can play before the entire API is loaded. To start playing quickly only the bare minimum is loaded:

  1. Eko Core - A subset of the Eko API which includes only the Player and the Decision Plugin.
  2. Project’s intro.js script, a programatic entry point which enables running custom code before the entire API is loaded. A common use case would be code that decides which node the project starts with. It also exposes a list of nodes which can be played throughout the intro (a.k.a Intro Nodes).
  3. The intro nodes.

By default only the head node of the project is included in the intro. Additional nodes can be marked as intro nodes by exporting their id in the introNodes property in intro.js. See JavaScript Entrypoints guide for details.

Loading Sequence

The following diagram provides a high level overview of the main steps in the loading sequence and the hooks that can be used by developers:

The resources required for the intro are loaded first, and once video starts playing the full Eko API and the project’s app.js are loaded and initialized.

The following hooks can be used by developers:

Hook File Description
onPreInit intro.js Called before the Eko Core is initialized. Can be used to modify the playerOptions dynamically based on query param or the user’s localstorage.
onPostInit intro.js Called after the Eko Core is initialized.
onIntroReady intro.js Called after some video has loaded. If autoplay was set, video will start playing immediately after this hook.
onReady app.js Called after the full Eko Runtime has finished loading.

In most cases your code entry point should be onReady. When executed, all the APIs are loaded and ready to use. The hooks defined in intro.js provide developers means to fine tune behaviors, but should not be used for the project’s heavy lifting. For example calling player.ui.override() in intro.js will emit an error since the ui plugin is not included in Eko Core. See JavaScript Entrypoints for details about the available hooks.

Video Playback

The video playback starts immediately after onIntroReady, unless autoplay is disabled. In those cases a Play button will be displayed for the user.

By the time onReady is called it is most likely that some video node is already playing. Since it’s an async flow developers must not assume that code defined in the onReady hook is executed before video is playing.

In your onReady implementation check the current playback state by looking into the player’s properties such as currentTime, currentNode or paused.

If the intro nodes playback ends before onReady the player will get into waiting state, as illustrated in the following diagram:

This is not a good user experience and should be avoided. It is usually a result of an intro node that is too short and bad network conditions. Pay attention to the way the intro is implemented to provide your users a great experience across devices and network conditions. We recommend the following patterns:

  1. On-boarding. Have an intro that serves as an on-boarding guide to the experience. If it’s 10 seconds or more it will provide the loader enough time to get to onReady even on bad networks.
  2. Looping video. If 10 seconds of on-boarding video does not work for your story, it’s recommended to have a short (3 seconds) node running in loop at the end of the on-boarding. Once onReady is called you stop the loop and seek to another node. The loop ensures that even in extreme cases users will see a video instead of a buffering UI. The following diagram illustrates this pattern:

In cases where on-boarding video does not work for your story, the lazy loading can be turned off. TBD.

Dynamic Head Nodes

Projects that use dynamic head nodes or use the headnodeid param should pay attention to all the alternative loading flows. Make sure that all the potential head nodes are defined as intro node.


Projects that use checkpoints and support resuming, allow users to continue watching the project where they last left off.
For those projects, if the user has checkpoints stored, playback doesn’t start until the Eko API is loaded. The onReady hook will be called right after playback begins.

Dynamic StreamingJavascript Entrypoints

Rate this page: X
Tell us more!