Integration guide

Note: How the flow works. Hive validates the JWT asynchronously, returns a HiveSession with the resolved manifest, and then your player loads session.manifest through the selected Hive technology.

Hive WebClient architecture

Most video players expose three groups of APIs. Hive WebClient uses each group to enable Hive consistently across different player platforms.

Hive Core HTML5 Plugin

The main library contains most Hive logic and binds each Hive session to the video playback session and its specific HTML5 video element.

• Session management initializes, activates, and deactivates the plugin.
• P2P logic hooks into player requests through the module so content can be delivered from other viewers.
• Analytics collects and publishes playback statistics while the session is active.
• Product logic enables Hive products such as Hive Control and Throughput Manager.

Hive Player Module

This helper library depends on the selected web player. It wraps and normalizes that player’s APIs for the Core Plugin.

• Video and audio track management
• Subtitle statistics
• Player request overrides

Important: Both libraries are required. The Core Plugin owns the Hive session and product behavior; the Player Module supplies the player-specific hooks it needs.

1. Install the plugin and player module

Import the Hive HTML5 plugin with the relevant technologies—HiveJava, HiveJS, and StatsJS. Hive also provides module libraries for different web players, so load the module that matches the player in your integration.

CDN scripts

<script src="https://media-players.hivestreaming.com/plugins/html5/13.3.0/html5.java.hivejs.hive.min.js"></script>
<script src="https://media-players.hivestreaming.com/common_libs/html5/videojs/hive-module.js"></script>

npm

Add Hive’s public Nexus registry to .npmrc:

@hivestreaming:registry=https://packages.hivestreaming.com/repository/npm-group/

Install the package:

npm install @hivestreaming/plugin-html5@13.3.0

Import the plugin and the module for your player:

import { HiveHtml5 } from "@hivestreaming/plugin-html5";
import { HiveVideoJsModule } from "@hivestreaming/plugin-html5/videojs/hive-module";

Yarn

Add Hive’s public Nexus registry to .npmrc:

@hivestreaming:registry=https://packages.hivestreaming.com/repository/npm-group/

Install the package:

yarn add @hivestreaming/plugin-html5@13.3.0

Import the plugin and the module for your player:

import { HiveHtml5 } from "@hivestreaming/plugin-html5";
import { HiveVideoJsModule } from "@hivestreaming/plugin-html5/videojs/hive-module";

2. Configure Hive for your player

Pass playerName and playerVersion when constructing the plugin. Hive uses both values in Insights reporting. Use onInitSession for successful initialization and onError for initialization and plugin failures.

const hivePluginOptions = {
  debugLevel: "debug",
  playerName: PLAYER_NAME,
  playerVersion: PLAYER_VERSION,
  onInitSession(session, plugin) {
    // Enable the player module and load session.manifest.
  },
  onError(message) {
    // Handle initialization and plugin errors.
  },
};

3. Initialize with JWT

Initialize the Hive Session with a JWT. initSession runs asynchronously and returns a HiveSession containing information about the video. Instantiate HiveHtml5 with the video tag itself or the ID of the HTML element that contains—or will contain—it.

const video = document.getElementById("video");
const plugin = new HiveHtml5(video, hivePluginOptions);

const session = await plugin.initSession({
  jwt,
  videoId,
  manifest,
});

Important: Provide the JWT, videoId, and manifest used when the JWT was created. The manifest must match its man claim.

4. Connect Hive to your player

After Hive initializes the session, enable the matching module and load the resolved session.manifest into the player. The complete examples also provide partner-owned CDN fallback logic.

Video.js

const player = videojs("example-video", { autoplay: true });

const options = {
  debugLevel: "debug",
  playerName: "video.js",
  playerVersion: videojs.VERSION,
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, videojs);
    player.src({ src: session.manifest, type: "application/x-mpegurl" });
  },
  onError(message) {
    if (message.severity > 0) player.src({ src: CDN_SOURCE });
  },
};

const plugin = new HiveHtml5("example-video", options);
plugin.initSession({ jwt, videoId, manifest });

THEOplayer

const player = new THEOplayer.Player("example-video");
const video = player.element.getElementsByTagName("video")[0];

const options = {
  playerName: "theoplayer",
  playerVersion: THEOplayer.version,
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, THEOplayer);
    player.source = {
      sources: [{ src: session.manifest, type: "application/x-mpegurl" }],
    };
  },
  onError(message) {
    if (message.severity > 0) {
      player.source = { sources: [{ src: CDN_SOURCE }] };
    }
  },
};

new HiveHtml5(video, options).initSession({ jwt, videoId, manifest });

HLS.js

const video = document.getElementById("example-video");
const player = new Hls();
player.attachMedia(video);

const options = {
  playerName: "hlsjs",
  playerVersion: Hls.version,
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, Hls);
    player.loadSource(session.manifest);
  },
  onError(message) {
    if (message.severity > 0) player.loadSource(CDN_SOURCE);
  },
};

const plugin = new HiveHtml5(video, options);
player.on(Hls.Events.MEDIA_ATTACHED, () =>
  plugin.initSession({ jwt, videoId, manifest })
);

Shaka Player

shaka.polyfill.installAll();
const video = document.getElementById("example-video");
const player = new shaka.Player(video);

const options = {
  playerName: "shaka",
  playerVersion: shaka.Player.version.substr(1),
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, shaka);
    player.load(session.manifest);
  },
  onError(message) {
    if (message.severity > 0) player.load(CDN_SOURCE);
  },
};

new HiveHtml5(video, options).initSession({ jwt, videoId, manifest });

JW Player

const player = jwplayer("example-video").setup({ file: CDN_SOURCE });

const options = {
  playerName: "jwplayer",
  playerVersion: jwplayer.version.match(/^([\w|.]*)/)[1],
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, jwplayer, session.manifest);
    player.play();
  },
  onError(message) {
    if (message.severity > 0) player.load({ file: CDN_SOURCE });
  },
};

const plugin = new HiveHtml5("example-video", options);
jwplayer().on("ready", () =>
  plugin.initSession({ jwt, videoId, manifest })
);

Bitmovin

const config = {
  key: BITMOVIN_KEY,
  playback: { autoplay: true, muted: true },
};
const player = new bitmovin.player.Player(video, config);

const options = {
  playerName: "bitmovin",
  playerVersion: bitmovin.playerui.version,
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, bitmovin);
    player.load({ hls: session.manifest });
  },
  onError(message) {
    if (message.severity > 0) player.load({ hls: CDN_SOURCE });
  },
};

new HiveHtml5("example-video", options).initSession({ jwt, videoId, manifest });

Vimeo

const video = document.getElementById("example-video");
const player = Vimeo.Player("iframe");

const options = {
  playerName: "Vimeo",
  playerVersion: "<player-build-version>",
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player);
    // Load session.manifest with your Vimeo integration.
  },
  onError(message) {
    if (message.severity > 0) cdnFallback();
  },
};

new HiveHtml5(video, options, setXHRFactory).initSession({
  jwt,
  videoId,
  manifest,
});

Flowplayer

HiveModule.initFlowplayer(flowplayer, "example-video");
const video = document.getElementById("example-video");

const options = {
  playerName: "flowplayer",
  playerVersion: flowplayer.version,
  onInitSession(session, plugin) {
    HiveModule.enable(plugin, player, flowplayer);
    player.load([{ src: session.manifest, type: "application/x-mpegurl" }]);
  },
  onError(message) {
    if (message.severity > 0) player.load([{ src: CDN_SOURCE }]);
  },
};

const player = flowplayer(video);
new HiveHtml5(video, options).initSession({ jwt, videoId, manifest });

5. Pass CDN authentication details

When private CDN content requires URL parameters or request headers, initialize Hive with the authentication mechanism. Hive can then cache those values and provide optimal WebRTC distribution.

URL parameters

const hivePluginOptions = {
  HiveJS: {
    requestCache: {
      queryParams: ["token", "expires"],
    },
  },
};

Request headers

const hivePluginOptions = {
  HiveJS: {
    requestCache: {
      headers: ["Authorization"],
    },
  },
};

6. Handle errors and CDN fallback

Three error types can occur:

1. Hive may fail to validate the JWT.
2. The plugin may fail during execution.
3. Playback may fail after the player loads the manifest.

Handle initialization and plugin errors in onError; handle playback errors with the specific player API.

Hive retries a session three times by default; configure this with errorRetrials. For backup streams, pass an authorization list so Hive can retry each stream in order. If re-initialization still fails, your onError callback should load the supporting CDN manifest.

const hivePluginOptions = {
  errorRetrials: 3,
  onError(message) {
    if (message.severity === 0) return; // NORMAL

    if (message.severity === 1) {
      // HIGH: Hive retries, then your integration falls back.
      cdnFallback();
    }

    if (message.severity === 2) {
      // CRITICAL: disable Hive and switch to the CDN.
      cdnFallback();
    }
  },
};

7. Understand the distribution technologies

Hive is called while the player initializes and supports three technologies. The package can combine them in order, attempting distribution first and falling back to Insights telemetry when distribution is unavailable.

Available package orders:

• HiveJava → HiveJS → StatsJS
• HiveJS → StatsJS
• HiveJava → StatsJS
• StatsJS only

Related documentation

• Partner authentication
• Customer management
• Plugin SDK 13.3.0