A number of APIs are necessary to send as part of your baseline app functions. These are the minimum required APIs in order for your app to function as a Firebolt® App.
Lifecycle baseline APIs
Lifecycle.ready()
The Lifecycle.Ready() method is used to inform the platform that your app is in a fully loaded state and is ready for the user to interact with it. You must call this method before dismissing your app’s loading screen. This method also automatically triggers the Metrics.ready() call, which contributes to the Time to Minimally Useable (TTMU) metrics.
Lifecycle.close()
The Lifecycle.close() method is used to request that the platform move your app out of focus and close the app session. Once called, your app must listen for the OS unloading event. Once the unloading event is received, the app should clear the associated listeners and send Lifecycle.finished() to finish the close request.
App session close guidance
There are use cases, such as during testing, where your app returns to the foreground before your app session is terminated, landing the user on the last seen UI (i.e., exit dialog). For better UX, your app should return to either your app’s homepage or the last screen prior to the exit dialog.
Parameters.initialization()
The Parameters.initialization() method is a required part of Lifecycle Management and is necessary for Deep Linking and app launch. It provides a payload that includes ad tracking and privacy opt-in/out flags, making it a key source for retrieving the user's ad tracking preferences.
Metrics baseline APIs
Metrics.appInfo()
The Metrics.appInfo() method is invoked at the start of the application to establish a link between subsequent events and a specific application version. The Metrics.appInfo() API should be invoked when the application starts from scratch, provided it has not been in background or suspended mode previously.
Metrics.ready()
The Metrics.ready() method informs the platform that your app is minimally usable and is automatically triggered by Lifecycle.ready().
Metrics APIs for content playback
Content and media playback apps require the following metrics APIs, but these APIs are not required for gaming and other non-playback apps.
Metrics.startContent()
The Metrics.startContent() method is a minimum requirement for all apps on the ppp Platform and contributes to the Errors Per Content Minute (EPCM) SLA metrics. It marks the beginning of user engagement with primary content. This API is called when a user is actively engaged with primary content, typically following explicit user interaction. In cases where the app launches directly into default content, this launch may count as explicit interaction. It’s important to distinguish between content previews and actual engagement. Metrics.startContent() and subsequent media APIs should only be used for content the user is truly consuming. For streaming media, Metrics.startContent() must be the first API call, made immediately before Metrics.mediaPlay() when using Media Metrics APIs.
Metrics.stopContent()
The Metrics.stopContent() method is also required for all apps and is part of the EPCM SLA metrics. It marks the end of user engagement with primary content. This method is called when the user finishes engaging with primary content. It requires that content was previously started in the current app lifecycle and may be triggered by user action or automatically by the app. It should be called after all media-related APIs.
Measuring content consumption vs. playback interactions
Firebolt metrics calls
Metrics.startContent()andMetrics.stopContent()to estimate content consumption time, not individual pause/unpause actions. Paused media is still considered as being consumed. To track actual playback interactions, useMetrics.mediaPlay()andMetrics.mediaPause()instead.
Metrics.mediaPlay()
The Metrics.mediaPlay() method is called whenever there is an explicit intent to play content, whether it's the initial action or a subsequent one such as unpausing previously paused media. If autoplay is enabled, Metrics.mediaPlay() should be called immediately before Metrics.mediaLoadStart(); if autoplay is disabled, it should be called just before instructing the player to begin playback. However, it should not be used when playback resumes after buffering, when switching back to primary content after an advertisement, or when changing HLS bitrates, as these do not represent new user playback intent.
Metrics.mediaPlaying()
The Metrics.mediaPlaying() method is called when media playback begins (or resumes from a different state) due to autoplay, user-initiated play, unpausing, or recovering from a buffering interruption.
Metrics.mediaLoadStart()
The Metrics.mediaLoadStart() method is called when setting the URL of a media asset to play in order to infer load time.
Metrics.mediaPause()
The Metrics.mediaPause() is called when media playback will pause due to an intentional pause operation.
Metrics.mediaRenditionChange()
The Metrics.mediaRenditionChange()is called when the playback rendition (bitrate, dimensions, profile, etc.) is changed.
Metrics.mediaSeeking()
The Metrics.mediaSeeking()is called when a seek is initiated during media playback.
Metrics.mediaSeeked()
The Metrics.mediaSeeked() is called when a seek is completed during media playback.
Metrics.mediaWaiting()
The Metrics.mediaWaiting() is called when media playback will halt due to a network, buffer, or other unintentional constraint.
Metrics.error()
The Metrics.error() method is a required component of the Error Free Session Rate (EFSR). This SLA metric includes a component that is a minimum requirement for all applications on the app platform. It shares a list of errors and corresponding troubleshooting guidelines with our platform to support testing and production. Proper implementation requires calling Metrics.error() for all errors occurring from app launch to exit, and ensuring each error is correctly tagged as either visible or not to the customer.
Metrics.mediaEnded()
The Metrics.mediaEnded() is called when playback has stopped because the end of the media was reached.