0.5.3-core-Metrics

Metrics

Article summary

Did you find this summary helpful?

Thank you for your feedback

Metrics Module 0.5.3

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

Events

Methods

ready

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

Promise Resolution

Type	Description
`boolean`

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

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

Promise Resolution

Type	Description
`boolean`

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

###### Response

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

signOut

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

Promise Resolution

Type	Description
`boolean`

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

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
}

##### 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
}

##### 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(null)
    .then(success => {
        console.log(success)
    })

Value of success

true

JSON-RPC

###### Request

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

###### Response

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

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 page metric

JavaScript

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

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

Value of success

true

JSON-RPC

###### Request

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

###### Response

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

##### Send startContent metric w/ entity

JavaScript

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

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

Value of success

true

JSON-RPC

###### Request

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

###### 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. See OpenRPC Schema for `oneOf` and `anyOf` details

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. See OpenRPC Schema for `oneOf` and `anyOf` details

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. See OpenRPC Schema for `oneOf` and `anyOf` details

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
}

Schemas

MediaPosition

type MediaPosition = void | number | bigint

Details

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.

ErrorType

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

Was this article helpful?

What's Next

Parameters

Table of contents

Usage
Overview
Events
Methods
Schemas