Version: 0.8.0

Metrics Module

Version 0.8.0

Overview

Methods for sending metrics

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-core-sdk GitHub repository.

You can see this API in the metrics.json OpenRPC JSON-Schema document.

Overview
OpenRPC
Usage
Methods

Schemas
- MediaPosition
- ErrorType

Usage

To use the Metrics module, you can import it into your project from the Firebolt SDK:

import { Metrics } from '@firebolt-js/sdk'

Methods

startContent

Inform the platform that your user has started content.

function startContent(entityId?: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	false	Optional entity ID of the content.

Promise resolution:

Type	Description
`boolean`

Examples

Send startContent metric

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.startContent(null)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.startContent",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

More examples...

Send startContent metric w/ entity

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.startContent("abc")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.startContent",
  "params": {
    "entityId": "abc"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

stopContent

Inform the platform that your user has stopped content.

function stopContent(entityId?: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	false	Optional entity ID of the content.

Promise resolution:

Type	Description
`boolean`

Examples

Send stopContent metric

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.stopContent(null)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.stopContent",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

More examples...

Send stopContent metric w/ entity

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.stopContent("abc")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.stopContent",
  "params": {
    "entityId": "abc"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

page

Inform the platform that your user has navigated to a page or view.

function page(pageId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`pageId`	`string`	true	Page ID of the content.

Promise resolution:

Type	Description
`boolean`

Examples

Send page metric

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.page("xyz")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.page",
  "params": {
    "pageId": "xyz"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

More examples...

Send startContent metric w/ entity

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.page("home")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.page",
  "params": {
    "pageId": "home"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

action

Inform the platform of something not covered by other Metrics APIs.

function action(category: 'user' | 'app', type: string, parameters?: FlatMap): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`category`	`'user'	'app'`	true
`type`	`string`	true	A short, indexible identifier for the action, e.g. 'SignIn Prompt Displayed' maxLength: 256
maxLength: 256
`parameters`	`FlatMap`	false

Promise resolution:

Type	Description
`boolean`

Examples

Send foo action

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.action("user", "The user did foo", null)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.action",
  "params": {
    "category": "user",
    "type": "The user did foo"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

error

Inform the platform of an error that has occured in your app.

function error(type: ErrorType, code: string, description: string, visible: boolean, parameters?: FlatMap): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`type`	`ErrorType`	true	The type of error
`code`	`string`	true	an app-specific error code
`description`	`string`	true	A short description of the error
`visible`	`boolean`	true	Whether or not this error was visible to the user.
`parameters`	`FlatMap`	false	Optional additional parameters to be logged with the error

Promise resolution:

Type	Description
`boolean`

Examples

Send error metric

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.error("media", "MEDIA-STALLED", "playback stalled", true, null)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.error",
  "params": {
    "type": "media",
    "code": "MEDIA-STALLED",
    "description": "playback stalled",
    "visible": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaLoadStart

Called when setting the URL of a media asset to play, in order to infer load time.

function mediaLoadStart(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send loadstart metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaLoadStart("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaLoadStart",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaPlay

Called when media playback should start due to autoplay, user-initiated play, or unpausing.

function mediaPlay(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send play metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaPlay("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaPlay",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaPlaying

Called when media playback actually starts due to autoplay, user-initiated play, unpausing, or recovering from a buffering interuption.

function mediaPlaying(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send playing metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaPlaying("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaPlaying",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaPause

Called when media playback will pause due to an intentional pause operation.

function mediaPause(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send pause metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaPause("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaPause",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaWaiting

Called when media playback will halt due to a network, buffer, or other unintentional constraint.

function mediaWaiting(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send waiting metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaWaiting("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaWaiting",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaProgress

Called every 60 seconds as media playback progresses.

function mediaProgress(entityId: string, progress: MediaPosition): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.
`progress`	`MediaPosition`	true	Progress of playback, as a decimal percentage (0-0.999) for content with a known duration, or an integer number of seconds (0-86400) for content with an unknown duration.

Promise resolution:

Type	Description
`boolean`

Examples

Send progress metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaProgress("345", 0.75)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaProgress",
  "params": {
    "entityId": "345",
    "progress": 0.75
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaSeeking

Called when a seek is initiated during media playback.

function mediaSeeking(entityId: string, target: MediaPosition): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.
`target`	`MediaPosition`	true	Target destination of the seek, as a decimal percentage (0-0.999) for content with a known duration, or an integer number of seconds (0-86400) for content with an unknown duration.

Promise resolution:

Type	Description
`boolean`

Examples

Send seeking metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaSeeking("345", 0.5)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaSeeking",
  "params": {
    "entityId": "345",
    "target": 0.5
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaSeeked

Called when a seek is completed during media playback.

function mediaSeeked(entityId: string, position: MediaPosition): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.
`position`	`MediaPosition`	true	Resulting position of the seek operation, as a decimal percentage (0-0.999) for content with a known duration, or an integer number of seconds (0-86400) for content with an unknown duration.

Promise resolution:

Type	Description
`boolean`

Examples

Send seeked metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaSeeked("345", 0.51)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaSeeked",
  "params": {
    "entityId": "345",
    "position": 0.51
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaRateChange

Called when the playback rate of media is changed.

function mediaRateChange(entityId: string, rate: number): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.
`rate`	`number`	true	The new playback rate.

Promise resolution:

Type	Description
`boolean`

Examples

Send ratechange metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaRateChange("345", 2)
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaRateChange",
  "params": {
    "entityId": "345",
    "rate": 2
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaRenditionChange

Called when the playback rendition (e.g. bitrate, dimensions, profile, etc) is changed.

function mediaRenditionChange(entityId: string, bitrate: number, width: number, height: number, profile?: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.
`bitrate`	`number`	true	The new bitrate in kbps.
`width`	`number`	true	The new resolution width.
`height`	`number`	true	The new resolution height.
`profile`	`string`	false	A description of the new profile, e.g. 'HDR' etc.

Promise resolution:

Type	Description
`boolean`

Examples

Send renditionchange metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaRenditionChange("345", 5000, 1920, 1080, "HDR+")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaRenditionChange",
  "params": {
    "entityId": "345",
    "bitrate": 5000,
    "width": 1920,
    "height": 1080,
    "profile": "HDR+"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

mediaEnded

Called when playback has stopped because the end of the media was reached.

function mediaEnded(entityId: string): Promise<boolean>

Parameters:

Param	Type	Required	Summary
`entityId`	`string`	true	The entityId of the media.

Promise resolution:

Type	Description
`boolean`

Examples

Send ended metric.

JavaScript:

import { Metrics } from '@firebolt-js/sdk'

Metrics.mediaEnded("345")
    .then(success => {
        console.log(success)
    })

Value of success:

true

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "metrics.mediaEnded",
  "params": {
    "entityId": "345"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Additional methods

The following methods are documented as part of a related set of method APIs.

For more information, follow the links under the "Documentation" column.

JavaScript	RPC	Parameters
NA	ready	`()`
NA	signIn	`()`
NA	signOut	`()`

Schemas

MediaPosition

Represents a position inside playback content, as a decimal percentage (0-0.999) for content with a known duration, or an integer number of seconds (0-86400) for content with an unknown duration.

type MediaPosition = void | number | number

ErrorType

type ErrorType = 'network' | 'media' | 'restriction' | 'entitlement' | 'other'

Metrics Module

Overview​

OpenRPC​

Table of Contents​

Usage​

Methods​

startContent​

stopContent​

page​

action​

error​

mediaLoadStart​

mediaPlay​

mediaPlaying​

mediaPause​

mediaWaiting​

mediaProgress​

mediaSeeking​

mediaSeeked​

mediaRateChange​

mediaRenditionChange​

mediaEnded​

Additional methods​

Schemas​

MediaPosition​

ErrorType​

Overview

OpenRPC

Table of Contents

Usage

Methods

startContent

stopContent

page

action

error

mediaLoadStart

mediaPlay

mediaPlaying

mediaPause

mediaWaiting

mediaProgress

mediaSeeking

mediaSeeked

mediaRateChange

mediaRenditionChange

mediaEnded

Additional methods

Schemas

MediaPosition

ErrorType