Timeline events
The fl-stream-timeline library facilitates streaming real-time events for an on-going live stream to enable rich, interactive Live experiences.
Create StreamTimelineManager
StreamTimeline configuration
Complete the required configuration before creating a StreamTimelineManager.
| Name | Required | Description |
|---|---|---|
| leagueName | true | The name of the league (case sensitive). |
| gameId | true | The unique identifier for the game. |
| spoiler | false | Indicates if the game events should be emitted ahead of the player watch position. |
val streamTimelineConfig = StreamTimelineConfig("NHL", "2022010075", false)
val streamTimelineManager = StreamTimelineFactory.createStreamTimelineManager(streamTimelineConfig, player, logger)
Refer to Firebase setup (follow only the first three steps) to add the configuration file to the project.
Firebase charges for document reads and writes, so we recommend creating the TimelineManager lazily.
Check if timeline events exist
To check whether timeline events are available for the given gameId, use:
streamTimelineManager.isPlayerEventsSubscriptionAvailable()
Set up subscription to timeline events
To set up the subscription for stream timeline events, use:
val result = streamTimelineManager.subscribeToPlayerEvents()
The subscribeToPlayerEvents API returns an Error when setup fails.
StreamTimelineManager publishes events only when the subscribeToPlayerEvents API is invoked and successful.
Listen to timeline events
Once you create the StreamTimelineManager, you can receive real-time stream timeline events on the Player instance.
Game info
The game metadata is made available via the StreamTimelineEvent.GAME_INFO event.
override fun onEventReceived(
streamTimelineEvent: StreamTimelineEvent,
suggestedAction: Action,
streamTimelineEventMetadata: StreamTimelineEventMetadata?) {
when(streamTimelineEvent) {
StreamTimelineEvent.GAME_INFO -> {
streamTimelineMetadata as StreamTimelineEventsMetadata
logger.trace { "game info is ${streamTimelineMetadata.events}" }
}
}
}
JSONSchema - Game Info
{
"id": {
"type": "string"
},
"matchNumber": {
"type": "string"
},
"season": {
"type": "string"
},
"series": {
"type": "string"
},
"scheduledStart": {
"type": "string",
"format": "date-time"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"venue_id": {
"type": "string"
},
"venue_name": {
"type": "string"
},
"game_year": {
"type": "string"
},
"teams": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"id": {
"type": "string"
},
"images": {
"type": "array",
"items": [
{
"type": "string"
}
]
},
"region": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"home",
"visitor"
]
},
"players": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"currentTeam": {
"type": "string"
},
"name": {
"type": "string"
},
"images": {
"type": "array",
"items": [
{
"type": "string"
}
]
},
"id": {
"type": "string"
},
"number": {
"type": "string"
},
"position": {
"type": "string"
}
}
}
]
}
}
}
]
}
}
}
Game event
The real-time game events are notified via the StreamTimelineEvent.GAME_EVENT event. The streamTimelineMetadata.streamTimelineEventAction indicates the StreamTimelineEventAction, which lets the application respond accordingly.
override fun onEventReceived(
streamTimelineEvent: StreamTimelineEvent,
suggestedAction: Action,
streamTimelineEventMetadata: StreamTimelineEventMetadata?) {
when(streamTimelineEvent) {
StreamTimelineEvent.GAME_EVENT -> {
streamTimelineMetadata as StreamTimelineEventsMetadata
when(streamTimelineMetadata.streamTimelineEventAction) {
StreamTimelineEventAction.ADDED -> {
//put your logic here
}
StreamTimelineEventAction.MODIFIED -> {
//put your logic here
}
StreamTimelineEventAction.DELETED -> {
//put your logic here
}
}
}
}
JSONSchema - Game Event
{
"description": {
"type": "string"
},
"id": {
"type": "string",
"format": "date-time"
},
"teamInvolved": {
"type": "string",
"enum": [
"home",
"visitor"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"period": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"period_start",
"period_end",
"overtime_start",
"overtime_end",
"shootout_start",
"shootout_end",
"break_start",
"break_end",
"goal",
"penalty",
"penalty_shot"
]
},
"startTime": {
"type": "string",
"format": "date-time"
},
"players": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"winner",
"loser",
"shooter",
"goalie",
"scorer",
"assist",
"unknown",
"blocker",
"hitter",
"hittee"
]
}
}
}
]
},
"scorecard": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"visitor": {
"type": "string"
},
"home": {
"type": "string"
}
}
},
"goals_by_period": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"visitor": {
"type": "string"
},
"home": {
"type": "string"
},
"period": {
"type": "string"
}
}
}
]
}
}
}
}
Stop listening to timeline events
Shut down the timeline manager when you close the player or when you're no longer interested in listening to stream timeline events.
streamTimelineManager.shutdown()