Metrics Module

Version Metrics 1.2.0

Table of Contents

• Table of Contents
• Usage
• Overview
• Methods
  • action
  • error
  • mediaEnded
  • mediaLoadStart
  • mediaPause
  • mediaPlay
  • mediaPlaying
  • mediaProgress
  • mediaRateChange
  • mediaRenditionChange
  • mediaSeeked
  • mediaSeeking
  • mediaWaiting
  • page
  • ready
  • signIn
  • signOut
  • startContent
  • stopContent
• Types
  • ErrorType
  • MediaPosition

Usage

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

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

Overview

Methods for sending metrics

Methods

action

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

function action(
  category: string,
  type: string,
  parameters: FlatMap,
): Promise<boolean>

Parameters:

Promise resolution:

Capabilities:

Examples

Send foo action

JavaScript:

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

let success = await Metrics.action('user', 'The user did foo', null)
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:

Capabilities:

Examples

Send error metric

JavaScript:

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

let success = await Metrics.error(
  'media',
  'MEDIA-STALLED',
  'playback stalled',
  true,
  null,
)
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
}

mediaEnded

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

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send ended metric.

JavaScript:

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

let success = await Metrics.mediaEnded('345')
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
}

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:

Capabilities:

Examples

Send loadstart metric.

JavaScript:

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

let success = await Metrics.mediaLoadStart('345')
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
}

mediaPause

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

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send pause metric.

JavaScript:

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

let success = await Metrics.mediaPause('345')
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
}

mediaPlay

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

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send play metric.

JavaScript:

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

let success = await Metrics.mediaPlay('345')
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:

Capabilities:

Examples

Send playing metric.

JavaScript:

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

let success = await Metrics.mediaPlaying('345')
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
}

mediaProgress

Called every 60 seconds as media playback progresses.

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send progress metric.

JavaScript:

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

let success = await Metrics.mediaProgress('345', 0.75)
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
}

mediaRateChange

Called when the playback rate of media is changed.

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send ratechange metric.

JavaScript:

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

let success = await Metrics.mediaRateChange('345', 2)
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:

Capabilities:

Examples

Send renditionchange metric.

JavaScript:

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

let success = await Metrics.mediaRenditionChange(
  '345',
  5000,
  1920,
  1080,
  'HDR+',
)
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
}

mediaSeeked

Called when a seek is completed during media playback.

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send seeked metric.

JavaScript:

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

let success = await Metrics.mediaSeeked('345', 0.51)
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
}

mediaSeeking

Called when a seek is initiated during media playback.

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send seeking metric.

JavaScript:

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

let success = await Metrics.mediaSeeking('345', 0.5)
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
}

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:

Capabilities:

Examples

Send waiting metric.

JavaScript:

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

let success = await Metrics.mediaWaiting('345')
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
}

page

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

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send page metric

JavaScript:

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

let success = await Metrics.page('xyz')
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
}

Send startContent metric w/ entity

JavaScript:

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

let success = await Metrics.page('home')
console.log(success)

Value of success:

true

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

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

ready

This is an private RPC method.

Inform the platform that your app is minimally usable. This method is called automatically by Lifecycle.ready()

Result:

Capabilities:

Examples

Send ready metric

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Metrics.ready",
  "params": {}
}

Response:

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

signIn

This is an private RPC method.

Log a sign in event, called by Discovery.signIn().

Result:

Capabilities:

Examples

Send signIn metric

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Metrics.signIn",
  "params": {}
}

Response:

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

Send signIn metric with entitlements

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Metrics.signIn",
  "params": {
    "entitlements": [
      {
        "entitlementId": "123",
        "startTime": "2025-01-01T00:00:00.000Z",
        "endTime": "2025-01-01T00:00:00.000Z"
      }
    ]
  }
}

Response:

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

signOut

This is an private RPC method.

Log a sign out event, called by Discovery.signOut().

Result:

Capabilities:

Examples

Send signOut metric

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Metrics.signOut",
  "params": {}
}

Response:

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

startContent

Inform the platform that your user has started content.

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

Parameters:

Promise resolution:

Capabilities:

Examples

Send startContent metric

JavaScript:

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

let success = await Metrics.startContent(null)
console.log(success)

Value of success:

true

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

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

Send startContent metric w/ entity

JavaScript:

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

let success = await Metrics.startContent('abc')
console.log(success)

Value of 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:

Capabilities:

Examples

Send stopContent metric

JavaScript:

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

let success = await Metrics.stopContent(null)
console.log(success)

Value of success:

true

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

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

Send stopContent metric w/ entity

JavaScript:

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

let success = await Metrics.stopContent('abc')
console.log(success)

Value of success:

true

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

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

Types

ErrorType

ErrorType: {
    NETWORK: 'network',
    MEDIA: 'media',
    RESTRICTION: 'restriction',
    ENTITLEMENT: 'entitlement',
    OTHER: 'other',
},

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