Skip to main content

Heartbeat

Heartbeat is an add-on functionality to the Quickplay Player that facilitates stream concurrency maintenance, maintaining last played position (for VOD) and enforcing geo-restrictions. For Live Streams, Heartbeat can notify the application of all applicable events during the stream.

Setup Heartbeat

Applicability

The corresponding (Authorize Playback for an Asset), for that playback holds the relevant information that indicate whether Heartbeat service is applicable for that playback

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.
liveEventTypeThe type of LIVE event i.e. regular or overflow, Applicable exclusively for live events.

Configuration

NameRequiredDescription
heartbeatEndPointUrltrueHeartbeat service end-point url.
streamConcurrencyEndPointUrlfalseStream Concurrency service end-point url. Default: ""
syncInterval600000LThe time interval in seconds used to periodically update stream state of the currently playing content. Default: 60000.
maxAllowedFailures2The 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.
postSlateDuration900000LThe time interval used to play post slate content for the specified duration.Default: 900000L
recordBookmarkfalseSpecifies whether to use the heartbeat service to record bookmarks/resume points for VOD contents. Default: false
stopOnPlaybackEndtrueSpecifies whether to use the heartbeat service to stop playback when the progame/event ends for live content
trackViewersCountfalseThe flag indicates whether to track the viewers count or not, for the content to play. Default value is false.
Create heartbeat Configuration
heartbeatConfig = FLHeartbeatFactory().heartbeatConfiguration(heartbeatEndPoint, streamConcurrencyEndpoint, syncInterval, maxAllowedFailures, postSlateDuration, recordBookmark, stopOnPlaybackEnd, trackViewersCount)

Track Watch Count

Watch count of the content can be tracked for business purpose. To extend support for Watch Count, additional param should be passed to heartbeatConfiguration instance. Along with all necessary information required to enforce Heartbeat, heartbeatConfiguration now encapsulates another optional param trackViewersCount to track the watch count of the content.

NameTypeDescription
trackViewersCountBooleanThe flag indicates whether to track the viewers count or not, for the content to play. Default value is false.

HeartbeatManager

NameDescription
configurationThe configuration for the heartbeat manager. Check HeartbeatConfiguration for further details.
deviceIdThe unique identifier of the device playing the stream
playbackAssetThe PlaybackAsset returned after the sucessful Authorization. It is response of content authorization service response.
PlatformAuthorizerThe PlatformAuthorizer instance to authorize Heartbeat Microservice access.
liveEventTypeThe type of LIVE stream. This value is part of the payload provided by content authorization service response.
overflowEventModeThe OverflowMode of the overflow LIVE stream. This value is part of the payload provided by content authorization service response.
HeadersThis is optional
 m._heartbeatManager = FLHeartbeatFactory().heartbeatManager(heartbeatConfig, DeviceId, playbackAsset, platformAuthorizer)

Attach Heartbeat to Player

HeartbeatManager provides processPlaybackStateChange and processPlaybackProgress methods that must be invoked on FLPlayer's value change on fields PLAYBACK_STATE and CURRENT_TIME respectively.

Process state change and progress change with heartbeat manager
sub initializeFLPlayer()
...

m.flPlayer.observeField(m.flPlayerFields.PLAYBACK_STATE, "onPlaybackStateChanged")
m.flPlayer.observeField(m.flPlayerFields.CURRENT_TIME, "onPlayheadPositionChanged")

...
end sub

sub onPlaybackStateChanged(event as Object)
if m.heartbeatManager <> invalid
if flPlayer.callFunc(flPlayerFunctions.IS_LIVE) then m.heartbeatManager.processPlaybackStateChange(m.flPlayer)
end if
end sub

sub onPlayheadPositionChanged(event as Object)
if m.heartbeatManager <> invalid
if flPlayer.callFunc(flPlayerFunctions.IS_LIVE) then m.heartbeatManager.processProgressChange(m.flPlayer)
end if
end sub

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 of the regular contentUrl.The blackout information is emitted as live event by FLPlayer. The blackoutUrl would be available with BlackoutUrl can be obtained from BlackoutMetadata.

The blackout information is emitted as live event by FLPlayer. The blackoutUrl would be available with the metadata associated with the event.

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 would emit streamtimelineevent event with blackout action via LIVE_EVENT field. Application can process the information and manage the blackout based on the UX requirements (typically, swap the on-going player with a player playing blacked-out slate).

Listening to live events from player

sub initializeFLPlayer()
...

m.flPlayer.observeField(m.flPlayerFields.LIVE_EVENT, "onLiveEvent")

...
end sub

sub onLiveEvent(event as Object)
? "Live Event: ", event.getData()
end sub

OverflowMode

Heartbeat uses the OverflowMode to detect when the playback has started i.e. before, during or after the event. This should be provided by the application while setting up Heartbeat.

     playerEpochTime = flPlayer.getField(flPlayerFields.CURRENT_EPOCH_TIME)
if m.liveEventType <> invalid and m.liveEventType = FLLiveEventType().OVERFLOW then
if m.overflowEventMode = FLOverflowEventMode().PRESLATE then
if m._liveStartTime <> invalid and m._liveStartTime > 0 and playerEpochTime >= m._liveStartTime then
' Send LiveEventStart event with suggestion action StartPlayback
event = FLPlayerLiveEvent(FLLiveEvents().LIVE_EVENT_START, FLPlayerActions().START_PLAYBACK)
flplayer.setField(flPlayerFields.LIVE_EVENT, event)
end if
else if m.overflowEventMode = FLOverflowEventMode().EVENT then
if m._liveEndTime <> invalid and m._liveEndTime > 0 and playerEpochTime >= m._liveEndTime then
' Send LiveEventEnd event with suggestion action NA
event = FLPlayerLiveEvent(FLLiveEvents().LIVE_EVENT_END)
flplayer.setField(flPlayerFields.LIVE_EVENT, event)
end if
else if m.overflowEventMode = FLOverflowEventMode().POSTSLATE then
if m._postSlateEndTime <> invalid and m._postSlateEndTime > 0 and playerEpochTime >= m._postSlateEndTime then
' Send OverflowEventEnd event with suggestion action NA
event = FLPlayerLiveEvent(FLLiveEvents().OVERFLOW_EVENT_END)
flplayer.setField(flPlayerFields.LIVE_EVENT, event)
m._stopIfConfigured(flPlayer)
end if
end if