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.

Name	Description
heartbeatFlag	Indicates whether heartbeat should be attached for the current playback (e.g., heartbeat is not required for blacked-out streams or certain VOD catalog types)
heartbeatFreq	The recommended heartbeat sync interval in milli-seconds
heartbeatToken	The unique hearbeat token for the current playback
liveStartTime	Start time of the current live program/live event.
liveEndTime	End Time of the current live program/live event.
catalogType	The value of the Catalog type of content.
primaryContentId	The 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.
live360StartTime	The start time of the live 360 camera supported content.
live360EndTime	The end time of the live 360 camera supported content.

Configuration

Name	Required	Description
heartbeatEndPointUrl	true	Heartbeat service end-point url.
streamConcurrencyEndPointUrl	true	Stream Concurrency service end-point url.
syncIntervalMS	false	The time interval in seconds used to periodically update stream state of the currently playing content. Default: 60000ms.
maxAllowedFailures	false	The 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.
recordBookmark	false	Specifies whether to use the heartbeat service to record bookmarks/resume points for VOD contents. Default: false.
trackViewersCount	false	The 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:

Name	Description
blackoutAction	Indicates appropriate action for Blackout scenario. Possible Values: ALLOW, DENY, ALLOW_WITH_UPGRADE.
blackoutUrl	The 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.

Name	Description
LIVE_EVENT_START	The start of a one-time Live event.
LIVE_EVENT_END	The end of a one-time live event.
OVERFLOW_EVENT_END	The end of an overflow event. Applicable only for Overflow events.
BLACKOUT	The playback has blacked out.
LIVE_360_AVAILABLE	The availability of 360 degree mode
LIVE_360_UNAVAILABLE	The unavailability of 360 degree mode