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 Authorization response 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	false	Stream Concurrency service end-point url.
syncInterval	TimeInterval	The time interval in milliseconds used to periodically update stream state of the currently playing content. Default: 60000.
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.
multiStreamMode	false	Specifies whether the current device is currently streaming multiple videos using multiple player instances.
playbackStopOnPlaybackEnd	true	Specifies whether to use the heartbeat service to stop playback when the progame/event ends for live content.
postSlateDuration	TimeInterval	The time interval used to play post slate content for the specified duration.
trackViewersCount	false	The flag indicates whether to track the viewers count or not, for the content to play. Default value is false.

let config = FLHeartbeatFactory.heartbeatConfiguration(heartbeatEndPointUrl: heartbeatEndPoint,
                                                               streamConcurrencyEndPointUrl: streamConcurrencyEndPoint, 
                                                               syncInterval: asset.heartbeatFrequency,
                                                               multiStreamMode: multiStreamMode,
                                                               syncInterval: syncInterval,
                                                               maxAllowedFailures: maxAllowedFailures,
                                                               recordBookmark: recordBookmark,
                                                               playbackStopOnPlaybackEnd: playbackStopOnPlaybackEnde,
                                                               postSlateDuration: postSlateDuration)
                                                               

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
contentId	The unique identifier of the stream
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.
heartbeatToken	The X-Heartbeat token.
authorizer	PlatformAuthorizer for creating authorized network request.Check PlatformAuthorizerfor further details
heartbeatService	Heartbeat Service, the Heartbeat Service contract
streamConcurrencyService	StreamConcurrency Service, the Stream Concurrency Service contract
heartbeatHeaders	Live event / program start time
liveStartTime	Live event / program type. Check LiveEventType for possible values.
liveEventType	The configuration for the heartbeat manager. Check HeartbeatConfiguration for further details.
overflowEventMode	Represent the current playable content. Check OverflowEventMode for possible values
live360StartTime	The start time of the live 360 camera supported content.
live360EndTime	The end time of the live 360 camera supported content.

let heartbeatManager = FLHeartbeatFactory.heartbeatManager(configuration: config,
                                                                   deviceId: deviceId,
                                                                   contentId: asset.contentId,
                                                                   catalogType: catalogType,
                                                                   primaryId: primaryId,
                                                                   heartbeatToken: heartbeatToken,
                                                                   authorizer: authorizer,
                                                                   heartbeatService: HeartbeatService,
                                                                   streamConcurrencyService: StreamConcurrencyService,
                                                                   heartbeatHeaders: heartbeatHeaders,
                                                                   liveStartTime: liveStartTime,
                                                                   liveEndTime: liveEndTimel,
                                                                   liveEventType: liveEventType,
                                                                   overflowEventMode: overflowEventMode,
                                                                   live360StartTime: live360StartTime,
                                                                   live360EndTime: live360EndTime)

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 HeartbeatConfig instance. Along with all necessary information required to enforce Heartbeat, HeartbeatConfig now encapsulates another optional param trackViewersCount to track the watch count of the content.

Name	Type	Required	Description
heartbeatEndPointUrl	String	True	The server url for heartbeat service.
streamConcurrencyEndPointUrl	String	True	The server url for stream concurrency service.
trackViewersCount	Boolean	False	The flag indicates whether to track the viewers count or not, for the content to play. Default value is false.

 let config = FLHeartbeatFactory.heartbeatConfiguration(heartbeatEndPointUrl: heartbeatEndPoint,
                                                            streamConcurrencyEndPointUrl: streamConcurrencyEndPoint,
                                                            trackViewerCount: environment?.trackViewerCount)

Attach Heartbeat to Player

HeartbeatManager provides processPlaybackStateChange and processPlaybackProgress methods that could be attached to a Player by adding them to Player's addStateChangeBlock and addHeartBeatBlock life-cycle methods respectively.

player.addStateChangeBlock(block: heartbeatManager.processPlaybackStateChange)
player.addHeartBeatBlock(block: heartbeatManager.processPlaybackProgress)

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. BlackoutUrl can be obtained from BlackoutMetadata. When receiving a blackoutAction other than ALLOW, the application must play the blackoutUrl instead of the regular contentUrl. BlackoutUrl can be obtained from BlackoutMetadata.

Roaming

Blackouts are 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 playback will be aborted and StreamTimelineEvent.BLACKOUT with corresponding Action and BlackoutMetadata(if any) will be propagated to the application via delegate, 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).

Overflow Events

Live events that do not have set start or end times are called Overflow events. These events typically show a pre-slate before the event starts, and dynamically switch to main content when the event eventually starts. Similarly, a post-slate is typically shown after the content has ended.

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.

func didReceive(event: StreamTimelineEvent, suggestedAction: Action, metadata: StreamTimelineMetadata?) {
    switch event {
    case .blackout:
        // handle blackout
    }
}

Handling StreamTimelineEvents

Heartbeat notifies the application of all applicable changes in the live stream to ensure that the playback is updated accordingly.

  // sends the given streamTimeLinevent along with suggested action and optional metadata
  func send(event: StreamTimelineEvent, suggestedAction: Action, metadata: StreamTimelineMetadata?) {

    // Handling some specific event
    switch event {
    case .liveProgramStart:
        // indicates the main content has started.
        // stop pre-slate playback and start the main content playback.
        startLiveEvent()
    case .liveEventEnd:
        // indicates the main content has ended.
        // stop main content playback and start the post-slate playback.
        endLiveEvent()
    case .overflowEventEnd:
        // indicates the post-slate has ended after
        // stop post-slate playback and exit.
        endLiveEvent()
    deafult:
    
     }
   }