Metrics Module

Version Metrics 1.0.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: 'user' | 'app', type: string, parameters?: object): Promise<boolean>

Parameters:

Promise resolution:

boolean

Capabilities:

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?: object): Promise<boolean>

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

mediaEnded

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

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

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:

boolean

Capabilities:

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
}

mediaPause

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

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

mediaPlay

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

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

Parameters:

Promise resolution:

boolean

Capabilities:

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:

boolean

Capabilities:

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
}

mediaProgress

Called every 60 seconds as media playback progresses.

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

mediaRateChange

Called when the playback rate of media is changed.

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

Parameters:

Promise resolution:

boolean

Capabilities:

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:

boolean

Capabilities:

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
}

mediaSeeked

Called when a seek is completed during media playback.

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

mediaSeeking

Called when a seek is initiated during media playback.

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

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:

boolean

Capabilities:

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
}

page

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

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

Parameters:

Promise resolution:

boolean

Capabilities:

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
}

Send startContent metric w/ entity

JavaScript:

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

Metrics.page("home")
    .then(success => {
        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:

boolean

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:

boolean

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:

boolean

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:

boolean

Capabilities:

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
}

Send startContent metric w/ entity

JavaScript:

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

Metrics.startContent("abc")
    .then(success => {
        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:

boolean

Capabilities:

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
}

Send stopContent metric w/ entity

JavaScript:

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

Metrics.stopContent("abc")
    .then(success => {
        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

enum 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