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

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

Configuration

Name	Required	Description
heartbeatEndPointUrl	true	Heartbeat service end-point url.
streamConcurrencyEndPointUrl	true	Stream Concurrency service end-point url.
syncInterval	600000L	The time interval in seconds used to periodically update stream state of the currently playing content. Default: 60000.
maxAllowedFailures	2	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.
postSlateDuration	900000L	The time interval used to play post slate content for the specified duration.Default: 900000L
recordBookmark	false	Specifies whether to use the heartbeat service to record bookmarks/resume points for VOD contents. Default: false
stopOnPlaybackEnd	true	Specifies whether to use the heartbeat service to stop playback when the progame/event ends for live content
trackViewersCount	false	The 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.

Name	Type	Description
trackViewersCount	Boolean	The flag indicates whether to track the viewers count or not, for the content to play. Default value is false.

HeartbeatManager

Name	Description
configuration	The configuration for the heartbeat manager. Check HeartbeatConfiguration for further details.
deviceId	The unique identifier of the device playing the stream
playbackAsset	The PlaybackAsset returned after the sucessful Authorization. It is response of content authorization service response.
PlatformAuthorizer	The PlatformAuthorizer instance to authorize Heartbeat Microservice access.
liveEventType	The type of LIVE stream. This value is part of the payload provided by content authorization service response.
overflowEventMode	The OverflowMode of the overflow LIVE stream. This value is part of the payload provided by content authorization service response.
Headers	This 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:

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 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