HTML App API

Posted by on October 16th, 2020

Intro

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

To provide seamless transitions, the Player performs preloading of the following content. Every time 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 the 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 the screen )
  6. The Widget is playing back normally.
  7. The hide_widget hook is called. (called just before the Widget is removed from the 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 Widget. 

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 that carries all the Widget configuration options defined for the Widget.

If a Widget does not provide configuration options, 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

The Widget shows a hook for the Widget. 

show_widget()

When playback stops, content on Player is first hidden and stopped 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 that 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 appears on screen to provide a 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 between loading the Widget and showing the Widget.
  • The Widget might need to know when to start playback., e.g., if 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.

Remember that this hook should be kept minimal and with zero delays since it may disrupt transitions.

hide_widget

The widget hides the 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.

Remember 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 that 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.

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 Playlist.

Note that this function 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.