Metrics

FL-Analytics is an add-on library that serves as a framework for recording comprehensive data metrics related to application, video playback, and user events. The library can also be used to collect custom events and metadata. The library's data model is based on the Data Dictionary which is the standard schema used to normalize every piece of data captured in order to generate many popular video streaming quality of experience metrics.

Setup

fl-analytics

1. Add the following snippet to your index.html file.

<script src="fl-analytics.iife.js"></script>

Application Session

ApplicationSession provides the entry point to the library analytics protocols. It also serves as factory containing APIs to create other analytic sessions (PlaybackSession and UserSession). Besides this ApplicationSession also provides APIs for reporting app start and report fatal and non-fatal errors.

Create sessions using the relevant APIs (each parameter content, playbackSource, applicationContainer and userInfo is discussed in detail in below sections).

// Create application session instance
const appSession = flAnalytics.getApplicationSession();

// API to initialize appliction session instance
appSession.initialize({
   configId: '<your-datazoom-key>',
   application: appInfo,
   device: deviceInfo,
   user: userInfo,
   customEventsConfigUrl: '<url-to-blacklisted-events-configuration>',
   logger: '<application-logger>'
});

// API to create PlaybackSession
const playbackSession = appSession.createPlaybackSession(content, playbackSource, applicationContainer);

// API to create UserSession
const userSession = appSession.createUserSession(userInfo);

note

Since ApplicationSession is a singleton class, flAnalytics.getApplicationSession() should be called only once. In case multiple calls are made to the API it will always return the same instance. Also note that ApplicationSession acts as a factory to create the remaining analytic session instances(UserSession and PlaybackSession).

The library supports connection to multiple analytics provider (supports Datazoom at present) by create configuration to specific analytic provider, below is the one for creating configuration for datazoom.

Reporting Data

The Metadata that is expected to remain constant for the entire duration of a session should be provided as an application, user, subscription or device information object. They encapsulate all relevant optional and mandatory metadata regarding different aspects of the analytics session.

note

Use API to update any of this common reporting data.

Application

Create application reporting data payload.

Name	Type	Required	Description
name	string	true	The name of the application.
version	string	true	The version of the application.
buildVersion	string	true	The build version of the application.
product	string	false	The customer product.

User

Create user's reporting data payload.

Name	Type	Required	Description
type	UserType	true	Indicates appropriate user type.
id	string	false	The unique user identifier (eg: Customer Id)
subscription	Subscription	false	User subscription details.
profileId	string	false	The unique identifier for the user's profile

Subscription

Create Subscription reporting data payload which will be reported as part of above user's payload.

Name	Type	Required	Description
id	String	true	The unique subscription identifier for the user.
status	SubscriptionStatus	false	Indicates appropriate subscription status.
plan	string	false	The subscription plan type name.
planID	string	false	The subscription plan type id

Device

Create user device's reporting data payload.

Name	Type	Required	Description
platformType	PlatformType	true	Represents how user consuming service (eg: APP, WEB)
customDeviceManufacturer	string	false	The manufacturer of the user's device if available.
customDeviceName	string	false	The name of the device model if available.

const appInfo = {
   name: 'Sample App Web',
   version: '7.0.57',
   build: '1.0.1'
}

const deviceInfo = {
   platformType: flAnalytics.PlatformType.WEB,
   customDeviceMfg: 'test mfg',
   customDeviceName: 'my pc'
}

const userInfo = {
   type: flAnalytics.UserType.SUBSCRIBED,
}

Initializing application session

Application session must be initialized before use. To initialize the application session, an object with the following properties must be passed as parameter.

Custom events reporting to the analytics server can be toggled on/off remotely. Passing the config end point URL, where the black-listed items are hosted, to the initialize method will restricts the reporting of black-listed custom events.

Name	Type	Required	Description
configId	string	true	Datazoom configuration key.
application	Object	true	An object containing the application information.
device	Object	true	An object containing the device information.
user	Object	false	An object containing the user information.
customEventsConfigUrl	string	false	The end point where custom events configuration details are hosted.
logger	Object	false	An object with a custom logger.

// API to initialize application session instance
appSession.initialize({
   configId: '<your-datazoom-key>',
   application: appInfo,
   device: deviceInfo,
   user: userInfo,
   customEventsConfigUrl: '<url-to-blacklisted-events-configuration>',
   logger: '<application-logger>'
});

Standard Playback Events & Metrics

Create PlaybackSession to report player related events.

const playbackSession = appSession.createPlaybackSession(content, playbackSource, applicationContainer);

Attach Player

PlaybackSession provides and API called attachPlayer which takes a Player instance as parameter. This API enables the underlying analytics collection tool to access platform native player instance, therefore auto-reporting most of the playback related events.

playbackSession.attachPlayer(player);

Playback events that are auto-captured by library itself

Name	Description
playback_start	This event is reported when the video starts playing for the user.
heartbeat	This event is reported at periodic intervals (1 minute) during content playback.
media_request	This event is reported after the user invokes playback.
player_ready	Signifies when the player has been initialized and is ready for playback.
pause	This event is reported when the player is paused.
resume	This event is reported when the user begins playing after pausing the video.
buffer_start	Buffer Start identifies anytime the player has to wait for the video buffer to fill with video segments.
buffer_end	Event is reported when video starts playing again after a buffer is completed.
stall_start	Stall Start event is reported when playback of video stops because the buffer has been depleted causing an unexpected interruption for the user.
stall_end	Event reported when video starts playing again after a stall and the buffer has been replenished and playback resumes.
error	Thrown if an error occurs during content playback or retrieval of the video.
playback_complete	This event signifies that the video player has reached the end of the currently playing content.
stop	This event is reported when the player has entered a stopped state.
milestone	Reported when the playheadPosition passes a predetermined percentile milestone of the video's duration. Current milestones are fired at the 10, 25, 50, 75, 90 & 95 percentiles.
seek_start	This event records when the user interacts with time controls within the player to move forward or backward in the video timeline.
see_end	Event is reported when the player stops moving the playhead position to jump to a specific point on the timeline.
playing	The media is no longer blocked from playback, and has started playing. Reported when playback resumes from Stall, Buffering or Seek.

Report Custom Playback Events

note

The Web implementation of FL-Analytics library provides support for multiple concurrent playback event reporting.

Report Playback Start

PlaybackSession provides API to report playback_request event.

PlaybackRequest

Content Specific metadata

Create data payload for specific type of contents as below.

SportContent

Create SportContent reporting data payload that is specific to sport event.

Name	Type	Required	Description
id	String	true	The unique identifier for content item.
type	String	true	The type of content to report.
name	String	true	The content name from CMS.
providerId	String	false	The content's provider identifier.
genre	String	false	The genre of the content.
licenseWindowStartDate	String	false	The license window start date. The clear content may not have this parameter.
sportName	String	true	The name of the sport.
leagueName	String	true	The name of the sport league.
team1Name	String	true	The name of the first sport team.
team2Name	String	true	The name of the second sport team.
leagueID	String	false	The unique identifier of the sport league.
leagueExternalID	String	false	The external unique identifier of the sport league.
leagueShortName	String	false	The short name of the sport league.
gameID	String	false	The unique identifier of the sport game.
gameExternalId	String	false	The external unique identifier of the sport game.
venue	SportVenue	false	The SportVenue instance.
team1ID	String	false	The unique identifier of the first sport team.
team1ExternalID	String	false	The external unique identifier of the first sport team
team1ShortName	String	false	The short name of the first sport team.
team2ID	String	false	The unique identifier of the second sport team.
team2ExternalID	String	false	he external unique identifier of the second sport team.
team2ShortName	String	false	The short name of the second sport team.

SportVenue

Create SportVenue reporting data payload that is specific to sport event.

Name	Type	Required	Description
venueName	String	true	The name of the sport event venue.
venueCity	String	true	The city where the sport event takes place.
venueCountry	String	true	The country where the sport event takes place.

TVShow

Create TVShow reporting data payload that is specific to TV show.

Name	Type	Required	Description
id	String	true	The unique identifier for content item.
type	String	true	The type of content to report.
name	String	true	The content name from CMS.
providerId	String	false	The content's provider identifier.
genre	String	false	The genre of the content.
licenseWindowStartDate	String	false	The license window start date. The clear content may not have this parameter.
seriesID	String	true	The unique identifier of the TV show series.
seriesName	String	true	The name of the TV show series.
seriesNumber	String	true	The season number of the TV show series.
episodeNumber	String	true	The number of one of the episodes in the TV show series.

MiscellaneousContent

Create MiscellaneousContent video content reporting data payload that belongs to categories other than SportContent or TVShow.

Name	Type	Required	Description
id	String	true	The unique identifier for content item.
type	String	true	The type of content to report.
name	String	true	The content name from CMS.
providerId	String	false	The content's provider identifier.
genre	String	false	The genre of the content.
licenseWindowStartDate	String	false	The license window start date. The clear content may not have this parameter.

ApplicationContainer

Create ApplicationContainer reporting data payload related to application container.

Name	Type	Required	Description
id	String	true	The unique identifier of the carousel where the content or link to the collection is located.
name	String	true	The name of the carousel where the content or link to the collection is located.

const container = {
   id: '456',
   name: 'Movies'
}

const content = {
   id: '5FB9F75D-EC44-4ACB-925E-84EBC303F47E',
   type: 'trailer',
   name: 'Entre gemelos anda el juego',
   providerId: 'magnolia',
   genre: 'Horror',
   seriesName: 'Seinfeld',
   seriesId: 'PYA1002904',
   seasonNumber: '2',
   episodeNumber: '5',
   licenseWindowStartDate: '2022-02-01 18:54:55.836 UTC'
}

const playbackSource = 'Carousel';

Handling Playback Request Interruptions

Any interruptions prior to starting the playback (before creating a player) can be reported using PlaybackSession API. Example: Checks related to content authorization (content authentication, parental controls etc)

// report interruption start
const customEvent = {
   event: 'content_authorization_started',
   data: {
      'key1': 'value1',
      'key2': 'value2'
   }
}

playbackSession.interruptStart(customEvent);

// report interruption end
const customEvent = {
   event: 'content_authorization_success',
   data: {
      'key1': 'value1',
      'key2': 'value2'
   }
}

playbackSession.interruptEnd(customEvent);

Configure Playback Metadata

Add Playback custom metadata

PlaybackSession provides an API that adds/updates common metadata to be reported across all playback related events.

playbackSession.setMetadata({
   'key1': 'value1',
   'key2': 'value2'
});

Report Playback Error

To report any error caused like content-auth failure, concurrent streams max limit reached (failure from server but not from player layer as FL-Analytics auto-reports player errors) can be reported using stop API in PlaybackSession. Send Error as a parameter(optional) to report playback stop on any error.

playbackSession.stop(error);

Value Added Events and Metrics

Application Events

Report Application start

ApplicationSession provides an API to report app_start event along with app start time.

// the time, in milliseconds, it takes to start the application
appSession.start(3000);

Report Application End

ApplicationSession provides an API to report app_end event.

appSession.stop();

User Events

UserSession provides the following API to report user action based events.

// Called when [User] executes "signup" flow.
userSession.signup(userInfo)

// Called when [User] executes "login" flow.
userSession.login(userInfo)

// Called when [User] executes "logout" flow.
userSession.logout(userInfo)

// Called when [User] executes "create profile" flow.
userSession.createProfile(userInfo)

// Called when [User] executes "update profile" flow.
userSession.updateProfile(userInfo)

// Called when [User] executes "start subscription" flow.
userSession.startSubscription(userInfo)

// Called when [User] executes "purchase subscription" flow.
userSession.purchaseSubscription(userInfo)

// Called when [User] executes "change subscription" flow.
userSession.changeSubscription(userInfo)

// Called when [User] executes "complete payment" flow.
userSession.completePayment(userInfo)

note

It is client application responsibility to ensure that each user action is triggered in the correct sequence.

Report Custom Events

ApplicationSession provides an API to report custom events.

const customEvent = {
   event: 'sample_event',
   data: {
      'key1': 'value1',
      'key2': 'value2'
   }
}

appSession.addEvent(customEvent);

note

1. In order to conform to the existing reporting scheme the event name should be provided in the lower case format and words should be separated by the underscore character e.g."playback_request"
2. In Datazoom, any custom event will be reported as event name with custom_ prefix. (eg: playback_start as custom_playback_start) :::

When trying to report a custom event with a name that is already reserved (the list of reserved event names is captured by QP_ANALYTICS_EVENTS), library will throw an error. :::

Configure Application Metadata

Set Application custom metadata

Additional metadata that is to be added or updated to all application / playback / user events can be done using the below API. All subsequent events will report this additional data once it is defined.

appSession.setMetadata({
  'key1': 'value1',
  'key2': 'value2'
});

Application Errors

ApplicationSession provides APIs to report both fatal and non-fatal errors.

Report Fatal errors

Any application fatal error can be reported using below API. Send Error as a parameter(optional) to report playback stop on any error.

applicationSession.stop(error)

Report Non-fatal errors

Any application non-fatal error can be reported using below API. Send Error to report playback stop on any error.

applicationSession.addErrorEvent(error)

User Action Errors

Any User error can be reported using below API. Create UserError reporting data payload in case where one of user's action fails and User attribute along with it.

Create User Error

Name	Type	Required	Description
code	String	true	The unique error code.
message	String	true	The message describing the error.
description	String	false	The contextual description of the error.

const userError = {
   code: '745',
   message: 'user action failure',
   description: 'user action failure details'
}

Out-of-box Player Metrics

The Quickplay Player provides number of key metrics to analyse the playback performance. Please refer the bundled sample app to understand the corresponding metrics API.

Key Player Metrics

• Load Latency - This is the number of seconds it took for the video element to have enough data to begin playback. This is measured from the time load() is called to the time the 'loadeddata' event is fired by then media element.

• Buffer Range - Indicates how much is buffered ahead of the playhead and how much is buffered behind the playhead (in seconds).

• Decoded Frames - The total number of frames decoded by the Player.

• Framerate - Provides number of Frames being displayed (per second).

• Dropped Frames - The total number of frames dropped by the Player.

• Corrupted Frames - The total number of corrupted frames dropped by the browser.

• Play Time - The total time spent in a playing state in seconds.

• Pause Time - The total time spent in a paused state in seconds.

• License Time - The time spent on license requests during this session in seconds, or NaN.

• Buffering Time - The total time spent in a buffering state in seconds.

• Required Bandwidth - The bandwidth required for the current streams (total, in bit/sec).

• Estimated Bandwidth - The current estimated network bandwidth (in bit/sec).

• Variant Bitrate - The bandwidth required to play active variant track, in bits/sec.

• Video Bitrate - The total time spent in a buffering state in seconds.

• Audio Bitrate - The bandwidth required for the current streams (total, in bit/sec).

• Width - The width of the current video track.

• Height - The height of the current video track.

The Quickplay Player's PlaybackStatistics provides all metric info required. For more information please refer sample app.

player.subscribe('progressupdate', function () {
  console.log(player.playbackStatistics);
});