---
title: "Firebolt Essentials"
slug: "firebolt-essentials"
updated: 2026-04-16T17:44:29Z
published: 2026-04-16T17:44:29Z
canonical: "docs.developer.comcast.com/firebolt-essentials"
---

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

# Firebolt Essentials

This guide will help you understand the core concepts needed to create streaming apps in Firebolt®. These essentials include installing Firebolt, importing modules, adding lifecycle functionality and reporting metrics.

---

## Install Firebolt and import modules

Installing Firebolt is simple because it's a publicly hosted package at [npmjs.com](https://www.npmjs.com/package/@firebolt-js/sdk). To set up Firebolt for use in your project:

1. Navigate to your desired project directory and run the following command:

```plaintext
npm install @firebolt-js/sdk
```
2. Import the desired modules in your code. Firebolt uses standard ECMAScript imports for all of its modules, allowing you to only import the modules you use. Here, we import the [Lifecycle](/docs/latest/core-lifecycle), [Metrics](/docs/latest/core-metrics), and [Device](/docs/latest/core-device) modules since they are needed to provide some basic functionality for your app.

```javascript
import { Lifecycle, Metrics, Device } from '@firebolt-js/sdk'
```
3. Use a module by simply referencing it and the desired method in your code. For example, your app likely wants to know which capabilities a given device has to ensure an optimal experience. Firebolt provides a number of convenient getters that you can use for this purpose, such as `videoResolution()` under the Device module.

```javascript
let [width, height] = await Device.videoResolution()
```

> [!NOTE]
> **Alternative Firebolt installations**
> 
> If you do not install Firebolt using npm, make sure that Firebolt is included as early as possible in your app’s main file. Including Firebolt late, or in component files, can result in race conditions or other unintended behavior.

---

## Add basic lifecycle to your app

The first thing your app will want to do is tell Firebolt that it's ready. Firebolt avoids assuming your app is minimally usable, and gives you complete control over when your app is ready to be presented to end users.

### Initialization and closing

When you've rendered enough of your app, just call [Lifecycle.ready()](http://docs.developer.comcast.com/latest/core-lifecycle#ready) as part of your app’s initialization. It's recommended to also listen for any Firebolt events *before* calling `Lifecycle.ready()` to ensure you don't miss any.

```javascript
async function init () {

  /*
  ...Initialization logic...
  */

  // Call Lifecycle.ready() to mark that the user can now navigate and interact with the app
  try {
      await Lifecycle.ready()
  } catch (err) {}
}
```

Once you have called `Lifecycle.ready()`, Firebolt knows that it's safe to present your app to end users and can do so as quickly as possible.

The `Lifecycle.close()` method instructs the platform to stop presenting your app to the user.

```javascript
try {
    Lifecycle.close('userExit')
} catch (err) {}
```

Once your app has been closed, it will move into background or inactive state depending on if media needs to continue playing. Refer to [Closing your App](https://docs.developer.comcast.com/docs/lifecycle-management#closing-your-app) for more details on this transition.

This method has a mandatory `reason` parameter that gives your app a way to influence which state it might be transitioned to. **In order to help the platform determine why your app is requesting to be closed, one of three reasons must be provided:**

1. `userExit` - The User explicitly selected an exit control that is rendered within your app UX.
2. `remoteButton` - The User pressed the `last` button on their remote from your app’s Home page.
3. `error` - Your app encountered an unrecoverable error, and needs to be exited.

### Listeners

Basic [event listeners](/docs/listening-for-events) must be used to properly implement Lifecycle. Events are a common pattern for asynchronous notifications from an SDK.

Firebolt provides three methods for interacting with Firebolt events:

1. `listen` - listens for only foreground events
2. `once` - listens for the very next instance of an event
3. `clear` - clears out all of the listeners for the entire module or just a single listener

```javascript
Lifecycle.listen('close', (value) => {
    if (value.previous === 'foreground') {
        console.log('Our app has transitioned from foreground to background!')
    }
})
```

---

## Report metrics for your app

Your app must implement Firebolt Metrics to ensure that the data generated by platform API calls can be used to properly triage and verify the health of your app.

At a high level, implementing metrics gives you feedback on what’s happening within your app and how user interactions are occurring. This includes launches, plays, pauses, errors (and what kinds of errors). These metrics reports can be very useful for monitoring how the app is performing and can provide data that can be used for improvements to your app. Careful selection and monitoring of metrics can help find issues to be resolved before the user even notices.

### App info metrics

[Metrics.appInfo()](https://docs.developer.comcast.com/latest/core-metrics#appinfo) is used to communicate the specific app version metrics events should be recorded for.

```javascript
// Package version that will be used as the appInfo build parameter value
const packageVersion = require('../package.json').version

async function init () {
  // App awaits appInfo with specified packageVersion as build.
  await Metrics.appInfo(packageVersion)
}
```

### Content minutes metrics

[Metrics.startContent()](/latest/core-metrics#startcontent) informs Firebolt which spans of time your user is watching content to aid in tracking frequency of errors.

To track this, call `Metrics.startContent()` before the user starts watching content:

```javascript
// App receives request from user to start playback of a content asset (represented here via Firebolt 'playback' intent)
if (intent.action == 'playback') {
  const entityId = intent.data.entityId
  // App calls Metrics.startContent() to inform the platform of the user request to start the primary content
  Metrics.StartContent(entityId)
  // initiate playback function for the specified primary content
  playById(entityId)
```

[Metrics.stopContent()](/docs/latest/core-metrics#stopcontent) informs Firebolt that the user has stopped content.

To track this, call `Metrics.stopContent()` when the user has finished watching content.

```javascript
// The user exits the content (represented here via the Firebolt 'home' intent).
if (intent.action == 'home') {
  const entityId = intent.data.entityId
  // If a video is currently loaded
  if (currentlyLoaded != null) {
    // App calls Metrics.stopContent()
    Metrics.stopContent(currentlyLoaded.id)
  }
  // Stop media playback
  stop()
}
```

> [!NOTE]
> **Identifiers are optional**
> 
> No identifiers are required for either of the content metrics above. This is because Firebolt does not track *what* the user is watching; it only tracks *how long* the user is watching.

### Error metrics

[Metrics.error()](/docs/latest/core-metrics#error) tracks errors in the app, monitoring the quality of both your app and the Firebolt experience, Firebolt needs to know when the user experiences errors in your app. Whenever an error occurs, simply pass the error to the Firebolt Metrics API. For example, to report a 404 network error when loading a required asset:

```javascript
Metrics.error('network', '404', true, 'The requested asset could not be found')
```

The codes and descriptions are completely up to you. The only granularity required is the first parameter, `type`, which can have one of five values:

1. `network` - A network error occurred.
2. `media` - A media playback related error occurred.
3. `restriction` - A policy restriction error occurred (e.g., content not available for the current region or device).
4. `entitlement` - An entitlement restriction occurred (i.e., user attempted to play content they are not entitled to).
5. `other` - Any other error occurred.

## Related

- [Baseline Firebolt APIs](/baseline-firebolt-api-implementations.md)
- [Lifecycle Management](/lifecycle-management.md)
- [Listening for Events](/listening-for-events.md)
- [Listening for Property Changes](/listening-for-property-changes.md)
- [Firebolt Metrics Implementation](/implementing-firebolt-metrics.md)