AMP Hive Plugin on MS Stream Documentation

Snippet Initialization

Since there is no ticket for the events, the plugin for MS doesn't need any snippet for the initialization. It will directly use the plain source list of the player.

---

Notes

The basic usage is illustrated above. The hive plugin is called while the player is being initialized, and currently supports three types of distributions (techs):

• HiveJava tech: distributes the video through the Java proxy client, works on every browser but supports only one video at the time.
• HiveJS tech: distributes the video between browsers using WebRTC, works only on WebRTC Datachannel enabled browsers, supports one video per page.
• StatsJS tech: no video distribution, only sends telemetry data for Insights analysis but works in every browser.

We currently have four different plugin packages with the following tech order combinations:

• [HiveJava + StatsJS]: attempts video distribution using the Hive Java client if installed and ready, falls back to only telemetries otherwise.
• [HiveJS + StatsJS]: attempts video distribution through the browser is supported, falls back to only telemetries otherwise.
• [HiveJava + HiveJS + StatsJS]: attempts video distribution using either Hive Java client if installed and ready or through the browser, falls back to only telemetries otherwise.
• [StatsJS]: only telemetries

The hiveTechOrder option defines the order in which the above techs within a particular plugin package should be attempted.

Other combination packages can be built on demand depending on the player support.

Handling Initialization and Playback Errors

As seen above, Hive initialization starts with a "ticket" that must be resolved into a real manifest to be played in the player. In general, there are two types of errors that can occur when using Hive, and both should be handled explicitly:

• Initialization error: Hive was not able to resolve the ticket.
• Playback error: After loaing manifest into the player, an error occurs during playback.

Initialization Errors

When Hive cannot resolve the ticket, it is impossible for the plugin to know what the supporting, real manifest is backing the ticket. This may occur if, for example:

• There is a mismatch between the plugin's hiveTechOrder and the viewer's machine's capabilities, eg. a value of ['HiveJava'] on a machine that does not have the Java Agent installed and is using a non-WebRTC capable browser.
• There was an issue communicating with the Hive Services backend.

All Hive plugins expose the ability to catch Hive initialization errors: see the usage example above for more information. In this scenario, it is up to the partner platform to continue with player initialization by either (a) explicitly loading the CDN manifest directly, or (b) retrying Hive with a (possibly new) ticket.

Playback Errors

After Hive successfully resolves the ticket, loading the real manifest into the player will begin playback using the initialized Hive technology. At this point, any number of scenarios may occur:

• During playback, the manifest becomes unreachable.
• The manifest was never reachable.
• The player cannot find new fragments in the manifest.

All Hive plugins will stop telemetry and "clean up" on a playback error. This means in order to "restart" Hive telemetries, the initialization flow MUST begin from the beginning -- resolving the ticket and loading the manifest into the player.

To improve user experience, these playback errors SHOULD be handled with a re-trial mechanism. The details are implementation-specific and highly dependent on failover / backup stream capabilities on the platform. A common failover mechanism is to alternate loading the Hive ticket and the supporting CDN manifest in a round-robin manner. If the platform supports backup streams (with Hive tickets), these streams can be added to the round-robin mix as well.

CDN authentication

When the CDN requires the use of specific URL parameters or request headers to access private content, Hive has to be initialized with additional information about the used authentication mechanism in order to cache the values and provide optimal distribution with WebRTC.

Authenticate with URL parameters

The plugin option HiveJS.requestCache.queryParams should be used to inform the name of the query string parameters required by the CDN.

Authenticate with headers

The plugin option HiveJS.requestCache.headers should be used to inform the name of the headers required by the CDN.