title: Metrics

# Metrics Module

Version 0.10.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.

Table of Contents

• Overview

• OpenRPC

• Usage

• Methods

  • startContent
  • stopContent
  • page
  • action
  • error
  • mediaLoadStart
  • mediaPlay
  • mediaPlaying
  • mediaPause
  • mediaWaiting
  • mediaProgress
  • mediaSeeking
  • mediaSeeked
  • mediaRateChange
  • mediaRenditionChange
  • mediaEnded
  • Additional 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:

Promise resolution:

Examples

Send startContent metric

JavaScript:

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

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

Value of success:

true

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

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

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

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

true

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

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

stopContent

Inform the platform that your user has stopped content.

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

Parameters:

Promise resolution:

Examples

Send stopContent metric

JavaScript:

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

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

Value of success:

true

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

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

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

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

true

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

{
  "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:

Promise resolution:

Examples

Send page metric

JavaScript:

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

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

Value of success:

true

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

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

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

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

true

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

Examples

Send loadstart metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

Examples

Send play metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

Examples

Send playing metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

Examples

Send pause metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

Examples

Send waiting metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

Examples

Send ratechange metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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:

Promise resolution:

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

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

{
  "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:

Promise resolution:

Examples

Send ended metric.

JavaScript:

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

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

Value of success:

true

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

{
  "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.

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'