Heartbeat
Heartbeat is an add-on functionality for the Quickplay Player that facilitates stream concurrency maintenance, maintains last played position (for VOD), and enforces geo-restrictions. For Live Streams, Heartbeat notifies your application of all applicable events during the stream.
Set up Heartbeat
You can determine whether Heartbeat is applicable for your playback by checking the Authorization response.
Applicability
The corresponding Authorization response for your playback contains the relevant information that indicates whether the Heartbeat service is applicable.
| Name | Description |
|---|---|
| heartbeatFlag | Indicates whether heartbeat should be attached for the current playback (for example, heartbeat isn't required for blacked-out streams or certain VOD catalog types) |
| heartbeatFreq | The recommended heartbeat sync interval in milliseconds |
| heartbeatToken | The unique heartbeat 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 (that is, regular or overflow). Applicable exclusively for live events |
Configuration
Configure the Heartbeat service with the parameters listed in the following table.
| Name | Required | Description |
|---|---|---|
| heartbeatEndPointUrl | true | Heartbeat service endpoint URL |
| streamConcurrencyEndPointUrl | false | Stream Concurrency service endpoint 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 program/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
The HeartbeatManager provides methods to configure and manage heartbeat functionality for your player. The following table describes the available configuration properties.
| 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 (that is, 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 PlatformAuthorizer for 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 | Represents 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
You can track the watch count of content for business purposes. To extend support for watch count, pass an additional parameter to the HeartbeatConfig instance.
Along with all necessary information required to enforce Heartbeat, HeartbeatConfig now encapsulates another optional parameter 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 you can attach 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 tenant-specific configuration. When you attempt a playback from a blacked-out region, the server responds 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 |
When receiving a blackoutAction other than ALLOW, your application must play the blackoutUrl instead of the regular contentUrl. You can obtain BlackoutUrl from BlackoutMetadata.
Roaming
Blackouts are detected and enforced via Heartbeat to ensure that when you roam to a blacked-out region, you're no longer able to stream the content. When detecting a blackout, the playback is aborted and StreamTimelineEvent.BLACKOUT with corresponding Action and BlackoutMetadata (if any) is propagated to your application via delegate. Your application can process the information and manage the blackout based on UX requirements (typically, swap the on-going player with a player playing blacked-out slate).
Overflow events
Live events that don't 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 (that is, before, during, or after the event). You should provide this while setting up Heartbeat.
func didReceive(event: StreamTimelineEvent, suggestedAction: Action, metadata: StreamTimelineMetadata?) {
switch event {
case .blackout:
// handle blackout
}
}
Handle StreamTimelineEvents
Heartbeat notifies your 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:
}
}