Skip to main content

Heartbeat

The heartbeat library is a personalization library that facilitates stream concurrency. Playback would be aborted when the concurrent streams reaches allowed limit.

Create HeartbeatManager

Wiring Authorization Response

Once an asset is authorized for Playback (refer Authorize Playback for an Asset), the authorization includes the following heartbeat info, which should be used while setting up the heartbeat.

NameDescription
heartbeatFlagIndicates whether heartbeat should be attached for the current playback (e.g., heartbeat is not required for blacked-out streams or certain VOD catalog types)
heartbeatFreqThe recommended heartbeat sync interval in milli-seconds
heartbeatTokenThe unique hearbeat token for the current playback
liveStartTimeStart time of the current live program/live event.
liveEndTimeEnd Time of the current live program/live event.
catalogTypeThe value of the Catalog type of content.
primaryContentIdThe unique identifier of the primary content to which the selected content (i.e. secondary angle content) to play is associated with. This is applicable only for multi-camera enabled content.
live360StartTimeThe start time of the live 360 camera supported content.
live360EndTimeThe end time of the live 360 camera supported content.

Configuration

NameRequiredDescription
heartbeatEndPointUrltrueHeartbeat service end-point url.
streamConcurrencyEndPointUrlfalseStream Concurrency service end-point url.
syncIntervalMSfalseThe time interval in seconds used to periodically update stream state of the currently playing content. Default: 60000ms.
maxAllowedFailuresfalseThe maximum number of failed heartbeat check attempts (network or infrastructure issues) that are allowed to happen in line before the Live content's playback is terminated. Default: 2.
recordBookmarkfalseSpecifies whether to use the heartbeat service to record bookmarks/resume points for VOD contents. Default: false.
trackViewersCountfalseThe flag indicates whether to track the viewers count or not, for the content to play. Default value is false.
const heartbeatConfiguration = {
heartbeatEndPointUrl: heartbeatEndPointUrl,
streamConcurrencyEndPointUrl: streamConcurrencyEndPointUrl,
syncIntervalMS: heartbeatFreq,
};

return flHeartbeat
.createHeartbeatBuilder(
deviceId,
contentId,
heartbeatConfiguration,
platformAuthorizer,
)
.setHeartbeatToken(heartbeatToken)
.setLiveEndTime(liveEndTime)
.setLiveStartTime(liveStartTime)
.build();

Attach Heartbeat to Player

HeartbeatManager could be attached to a Player by attaching the exposed processPlayerStateChange, processHeartbeatChange callback to ComposablePlayer's addStateChangeStep, processHeartbeatChange life-cycle method.

const composablePlayer = flPlatformPlayer.createComposablePlayer(player);
composablePlayer.addStateChangeStep(heartbeatManager.processPlayerStateChange);

composablePlayer.addHeartBeatStep(heartbeatManager.processHeartbeatChange);

Blackouts

While authorizing an asset for Playback, the server might enforce Blackout rules based on tenent specific configuration. When a playback is attempted from a Blacked-out region, the server would respond with the following:

NameDescription
blackoutActionIndicates appropriate action for Blackout scenario. Possible Values: ALLOW, DENY, ALLOW_WITH_UPGRADE.
blackoutUrlThe alternate blackout slate stream to play while the user is in blackout.
note

When receiving a blackoutAction other than ALLOW, the application must play the blackoutUrl instead if the regular contentUrl.

Roaming

Blackouts are also detected and enforced via heartbeat to ensure when the user is roaming to a blacked-out region, they are no longer able to stream the content. When detecting a blackout, the HeartbeatManager would abort the player and player emits a streamtimelineevent event with blackout action. Application could subscribe to this event manage the blackout based on the UX requirements (typically, swap the on-going player with a player playing blacked-out slate).

  player.subscribe("streamtimelineevent", async function (streamTimelineEvent, action, metadata) {

switch (streamTimelineEvent) {
case flPlayerInterface.StreamTimelineEvent.BLACKOUT: {
console.log("Blackout Url", blackoutMetadata.blackoutUrl);
// Create a new player instance and play the blackout Url.
break;
}
}

});

Events during Live Streams

All the applicable events for different type of live streams are part of StreamTimelineEvent and can be notified to the client application using Heartbeat.

NameDescription
LIVE_EVENT_STARTThe start of a one-time Live event.
LIVE_EVENT_ENDThe end of a one-time live event.
OVERFLOW_EVENT_ENDThe end of an overflow event. Applicable only for Overflow events.
BLACKOUTThe playback has blacked out.
LIVE_360_AVAILABLEThe availability of 360 degree mode
LIVE_360_UNAVAILABLEThe unavailability of 360 degree mode