HTML App API

Posted by on October 16th, 2020

The Player needs to notify the App of the current state of playback. The Player calls several hooks during playback, so that the App can properly update its status. Also, the Player provides an API to allow the App to perform actions or retrieve additional information from the Player.

Sequence of Calls

In order to provide seamless transitions, the Player performs preloading of the content that follows. Every time a content is shown on screen, the next item in the Playlist is loaded, so that the transition is as fast as possible.

The standard sequence of events is the following:

  1. The App is loaded on the Player’s web viewer.
  2. The init_widget hook is called. (called right after the Widget loading has completed)
  3. The Widget awaits preloaded to be shown on screen.
  4. The show_widget hook is called. (called just before the Widget is shown on screen)
  5. The start_widget hook is called. (called just after the Widget is shown on screen )
  6. The Widget is playing back normally.
  7. The hide_widget hook is called. (called just before the Widget is removed from screen )
  8. The stop_widget hook is called. (called just after the Widget is removed on screen )
  9. The Widget awaits to be destroyed.
  10. The Player’s web viewer is destroyed .

HTML App Hooks

init_widget

Initialization hook for the App. 

init_widget(config)

This is the most frequently used hook. This hook is called right after the Widget has completed loading. The config argument is an object, which carries all the Widget configuration options that have been defined for the Widget.

If a Widget does not provide any configuration options, then you can safely skip providing this function in your Widget code. Note that this hook is called just after the onload() call completes.

show_widget

App show hook for the Widget. 

show_widget()

When playback stops, content on Player is first hidden and stopped, in order to provide a much more seamless transition between content (stopping may take more time than hiding). This hook is called right before the Widget viewer is destroyed. This hook might be needed in the following cases:

  • The Widget saves some state on a backend server when it finishes, so it needs to do some work before it is terminated.
  • The Widget might use CPU or bandwidth until the web viewer is actually destroyed, so these resources can be saved in the meantime.

You can safely skip providing this function in your Widget code, if you do not need it.

start_widget

Playback start hook for the Widget. 

start_widget()

Content on Player is preloaded before it shows up on screen, in order to provide a much more seamless transition between content. This hook is called right after the Widget has been shown on screen. This hook might be needed in the following cases:

  • The Widget is CPU intensive, so you can use it to prevent unnecessary CPU load during the time between loading the Widget and showing the Widget.
  • The Widget might need to know when to start playback., e.g. in the case that it needs to  playback a series of images.
  • The Widget might use bandwidth to update its data, so bandwidth can be saved if updates do not occur when the Widget is not visible.

You can safely skip providing this function in your Widget code, if you do not need it.

Keep in mind that this hook should be kept minimal and with zero delays, since it may disrupt transitions.

hide_widget

Widget hide hook for the Widget. 

hide_widget()

This hook is called right before the Widget viewer is moved off-screen. The use cases for this hook are very rare.

You can safely skip providing this function in your Widget code, if you do not need it.

Keep in mind that this hook should be kept minimal and with zero delays, since it may disrupt transitions.

stop_widget

Playback stop hook for the Widget. 

stop_widget()

This hook is called right after the Widget viewer has been moved off screen. This hook might be needed in the following cases:

  • The Widget saves some state on a backend server when it finishes, so it needs to do some work before it is terminated.
  • The Widget might use CPU or bandwidth until the web viewer is actually destroyed, so these resources can be saved in the mean time.

You can safely skip providing this function in your Widget code, if you do not need it.

HTML Widget API Calls

exit_widget

Notify the Player that the Widget has finished playback. 

exit_widget()

This function allows your Widget to notify the Player that the Widget has completed playback and the viewer should terminate. This allows your Widget to get the Player to proceed to the next content item in the current Playlist.

Note that this function just notifies the Player; it does not cause the Widget to exit instantly. The Player will go through the transition flow, calling all required hooks detailed above.