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. To set up Firebolt for use in your project:

Navigate your desired project directory and run the following command:
```
npm install @firebolt-js/sdk
```
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, Metrics, and Device modules since they are needed to provide some basic functionality for your app.
```
import { Lifecycle, Metrics, Device } from '@firebolt-js/sdk'
```
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 since some devices are more powerful than others. Firebolt provides a number of convenient getters that you can use for this purpose, such as videoResolution() under the Device module.
```
let [width, height] = await Device.videoResolution()
```

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() 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.

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.

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

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

Listeners

Basic event listeners 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:

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

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() is used to communicate the specific app version metrics events should be recorded for.

// 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() 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:

// 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() informs Firebolt that the user has stopped content.

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

// 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()
}

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() 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:

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:

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