Our newest offerings and the EntertainmentOS system are built on the Firebolt® API. If you currently maintain a legacy (also known as $badger or MoneyBadger) X1 app, you may be curious about the benefits of using Firebolt. This document is meant to both explain the benefits of transitioning, and offer a pathway to start transitioning to the Firebolt API.
Looking for the original Transitioning from Legacy page? That is now located at Badger to Firebolt Reference.
Rationale
Our scaled devices have been a staple of customer households for years. However, continuous development on the technology supporting them has caused technical debt to accumulate over time. Additionally, partners were forced to rely on direct guidance to properly develop for our scaled devices.
The creation of Firebolt was a way to improve on the imperfections of our legacy stack, while also having the capability to support more and stronger devices. The two primary goals of Firebolt are to ensure that:
- Development of Firebolt apps is as simple as possible
- Firebolt apps are able to work on all of our offerings
To meet these goals, we focused on improving three main aspects: standardization, consistency, and ease.
-
Standardization: With legacy codebases, we found that many partners created multiple versions of their apps to service the wide variety of OTT devices and TVs offered by Comcast and other distributors. These separate versions created extra development overhead, as different devices could have wildly different capabilities and specifications. This versioning is no longer necessary with Firebolt, since certified Firebolt apps can run on every EntertainmentOS offering - past, present, and future.
-
Consistency: Alongside no longer needing separate app versions (which avoids bespoke development for different devices, distributors, and regions), certified Firebolt apps will run nearly the exact same way on every EntertainmentOS device. Additionally, leveraging the improved capabilities of higher-end devices, catching important app events, and tracking metrics have been simplified.
-
Ease: While we made using a Firebolt app as simple as possible for users, we also wanted to do the same for developing (and testing) a Firebolt app. To this end, we've created comprehensive documentation for the Firebolt API and made testing Firebolt apps simple. With Mock Firebolt, you may not even need a test device until late in development — if at all.
With development being standardized, partners should no longer have to rely on slow guided progress and constant check-ins. With testing simplified, partners can catch and fix issues quickly. As a result, development times will be shorter and partners can quickly reach (and pass) certification. The time between onboarding and your app reaching millions of devices is the shortest it has ever been.
Functionality differences
While Firebolt maintains much of the functionality that our legacy API had, it also comes with multiple changes and additions to take advantage of EntertainmentOS' stronger capabilities.
Modern implementation
Our legacy technology was a RESTful API distributed as a full package, which caused two downstream issues. The first was that developers who did not need or want specific features had to deal with extra memory overhead from the unused modules. The second was our legacy API had to maintain state for multiple endpoints. In contrast, the Firebolt API is a JSON-RPC implementation. This makes Firebolt simpler to use, easier to troubleshoot, and stateless. Additionally, our supplementary JavaScript SDK is modular - you will only load the modules you actively use, saving memory for more important tasks and processes.
Lifecycle management
With our legacy API, only a single app could be in focus. With Firebolt's Lifecycle API, one app can have focus while another app can play music (or video) in the background. Additionally, apps can maintain their state by suspending themselves in case a user would like to return. More information can be found in our Lifecycle Management guide.
Child privacy
Firebolt supports features to help partners comply with child privacy rulings such as COPPA. By properly tagging Metrics data and watch history as coming from a child, Firebolt will ensure that such data is discarded and not used for any personalization or advertising. The same is done for any content that is made for children. More information can be found on our child-directed guidelines page.
Event listeners
In order to watch for changes in a user's settings, our legacy API required calls to be kept open — otherwise, you would likely miss a crucial setting change when you needed it most. This cumbersome RESTful API requirement resulted in extra memory overhead. Firebolt instead offers dedicated listener functions across many modules, alongside more granular events. Additionally, managing event listeners is much easier — allowing apps to listen to a single event in a module, all events in a module, or only the next instance of an event. Apps can also clear any unnecessary listeners individually or in bulk. More information can be found in our Listening for Events guide.
Deep links
While the concept of deep links existed in our legacy API, Firebolt standardizes the feature and makes it easily available for developers to integrate into their app. Deep Linking allows apps to open directly to specific screens, app areas, and content when a user selects an item in the EntertainmentOS platform.
Legacy calls
This section provides information on legacy calls and their Firebolt replacements, as well as providing additional resources.
Required legacy calls
Listed below are the required implementations from our legacy API grouped by category, and their closest Firebolt equivalent(s).
App State Management
$badger.dismissLoadingScreen()
Replace with: Lifecycle.ready()
EntOS wants to know when your app will be ready to use. Additionally, Lifecycle.ready() also preforms two related functions: calling Metrics.ready() and contributing data to calculate the Time To Minimally Usable (TTMU), one of the Operational Requirements for apps.
$badger.shutdown()
Replace with: Lifecycle.close() & Lifecycle.finished()
Lifecycle.close() removes your app from focus and prepares it for future unloading. Once you have received an unloading request from the OS, Lifecycle.finished() completes the close process. Unlike our legacy API, Lifecycle.close() requires that you specify a closure reason to assist EntOS on deciding which state your app should move to.
Metrics
$badger.appActionMetricsHandler()
Replace with: Metrics.startContent() & Metrics.stopContent()
EntOS tracks the amount of time a user spends consuming content through Metrics.startContent() and Metrics.stopContent(). The time spent is used to calculate the Errors Per Content Minute (EPCM), one of the Operational Requirements for apps.
$badger.errorMetricsHandler()
Replace with: Metrics.error()
Metrics.error() tracks errors in your app to calculate your app’s Error Free Session Rate (EFSR), one of the Operational Requirements for apps.
Notifications
$badger.showToaster()
This endpoint has been deprecated. Apps are no longer required to display notifications upon an exit.
Additional legacy calls
Depending on the structure and functionality of your app, you may require additional legacy calls beyond the minimal required calls. Additionally, you may be curious about the required implementations for Firebolt apps.
For information on those legacy calls (and their Firebolt replacements) and Firebolt's required implementations, refer to the following resources:
Certification
A certified app will be able to function well on all of our device offerings, ensuring that customers will have a good experience with both your apps and the EntertainmentOS system.
All apps must meet our Baseline Functionality Requirements in order to be certified and published on the EntOS platform. Additionally, partners using specific platform features or integrations must also ensure that they meet any corresponding Feature Requirements and Integration Requirements.