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 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:
- Eko Core - A subset of the Eko API which includes only the Player and the Decision Plugin.
intro.jsscript, 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).
- 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
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:
||Called before the Eko Core is initialized. Can be used to modify the playerOptions dynamically based on query param or the user’s localstorage.|
||Called after the Eko Core is initialized.|
||Called after some video has loaded. If autoplay was set, video will start playing immediately after this hook.|
||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.jsprovide developers means to fine tune behaviors, but should not be used for the project’s heavy lifting. For example calling
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.
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:
- 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
onReadyeven on bad networks.
- 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
onReadyis 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.
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.