---
title: "Metrics"
slug: "081-core-metrics"
updated: 2025-05-23T22:35:34Z
published: 2025-05-23T22:35:34Z
canonical: "docs.developer.comcast.com/081-core-metrics"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.developer.comcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics

**Metrics Module 0.8.1 | Core SDK**

## Overview

Methods for sending metrics

## OpenRPC

Firebolt APIs are maintained in the [rdkcentral/firebolt-core-sdk](https://github.com/rdkcentral/firebolt-core-sdk) GitHub repository.

You can see this API in the [metrics.json](https://github.com/rdkcentral/firebolt-core-sdk/blob/main/src/modules/metrics.json) OpenRPC JSON-Schema document.

## 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`](/docs/081-core-Types-schemas#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`](/docs/081-core-metrics#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`](/docs/081-core-Types-schemas#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`](/docs/081-core-metrics#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`](/docs/081-core-metrics#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`](/docs/081-core-metrics#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 | Documentation |
| --- | --- | --- | --- |
| *NA* | ready | `()` | [](/docs/081-core-metrics#) |
| *NA* | signIn | `()` | [](/docs/081-core-metrics#) |
| *NA* | signOut | `()` | [](/docs/081-core-metrics#) |

## 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'
```

---