title: Lifecycle

version: 0.8.1
layout: default
sdk: core

# Lifecycle Module

Version 0.8.1

Overview

Methods and events for responding to lifecycle changes in your app

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-core-sdk GitHub repository.

You can see this API in the lifecycle.json OpenRPC JSON-Schema document.

Table of Contents

• Lifecycle Module
  • Overview
  • OpenRPC
  • Table of Contents
  • Usage
  • Methods
    • close
    • finished
    • listen
    • once
    • ready
    • state
  • Events
    • background
    • foreground
    • inactive
    • suspended
    • unloading
  • Schemas
    • LifecycleEvent

Usage

To use the Lifecycle module, you can import it into your project from the Firebolt SDK:

import { Lifecycle } from '@firebolt-js/sdk'

Methods

close

Request that the platform move your app out of focus

function close(reason: CloseReason): Promise<void>

Parameters:

Promise resolution:

void

Examples

Close the app when the user presses back on the app home screen

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.close("remoteButton")
    .then(success => {
        console.log(success)
    })

Value of success:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.close",
  "params": {
    "reason": "remoteButton"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.close("userExit")
    .then(success => {
        console.log(success)
    })

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.close",
  "params": {
    "reason": "userExit"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

finished

Notify the platform that the app is done unloading

function finished(): Promise<void>

Promise resolution:

void

Examples

Default Example

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.finished()
    .then(results => {
        console.log(results)
    })

Value of results:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.finished",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

listen

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

Lifecycle.listen(event: string, (data: any) => void): Promise<number>

Parameters:

Promise resolution:

Callback parameters:

To listen to all events from this module pass only a callback, without specifying an event name:

Lifecycle.listen((event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

once

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

Lifecycle.once(event: string, (data: any) => void): Promise<number>

Parameters:

Promise resolution:

Callback parameters:

To listen to all events from this module pass only a callback, without specifying an event name:

Lifecycle.once((event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

ready

Notify the platform that the app is ready

function ready(): Promise<void>

Promise resolution:

void

Examples

Let the platform know that your app is ready

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.ready()
    .then(result => {
        console.log(result)
    })

Value of result:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.ready",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

state

Get the current state of the app. This function is synchronous.

function state(): LifecycleState

Promise resolution:

Examples

Default Example

JavaScript:

import { Lifecycle } from ''

const state = Lifecycle.state()
console.log(state)

Value of state:

"foreground"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.state",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "foreground"
}

Events

background

Listen to the background event

See also: listen(), once(), clear().

Event value:

Examples

Default Example:

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('background', value => {
  console.log(value)
})

Value of value

{
  "state": "background",
  "previous": "foreground"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onBackground",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "background",
    "previous": "foreground"
  }
}

foreground

Listen to the foreground event

See also: listen(), once(), clear().

Event value:

Examples

Default Example:

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('foreground', value => {
  console.log(value)
})

Value of value

{
  "state": "foreground",
  "previous": "inactive"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onForeground",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "foreground",
    "previous": "inactive"
  }
}

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('foreground', value => {
  console.log(value)
})

{
  "state": "foreground",
  "previous": "inactive",
  "source": "remote"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onForeground",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "foreground",
    "previous": "inactive",
    "source": "remote"
  }
}

inactive

Listen to the inactive event

See also: listen(), once(), clear().

Event value:

Examples

Default Example:

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('inactive', value => {
  console.log(value)
})

Value of value

{
  "state": "inactive",
  "previous": "initializing"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onInactive",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "inactive",
    "previous": "initializing"
  }
}

suspended

Listen to the suspended event

See also: listen(), once(), clear().

Event value:

Examples

Default Example:

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('suspended', value => {
  console.log(value)
})

Value of value

{
  "state": "suspended",
  "previous": "inactive"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onSuspended",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "suspended",
    "previous": "inactive"
  }
}

unloading

Listen to the unloading event

See also: listen(), once(), clear().

Event value:

Examples

Default Example:

JavaScript:

import { Lifecycle } from '@firebolt-js/sdk'

Lifecycle.listen('unloading', value => {
  console.log(value)
})

Value of value

{
  "state": "unloading",
  "previous": "inactive"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "lifecycle.onUnloading",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "unloading",
    "previous": "inactive"
  }
}

Schemas

LifecycleEvent

A an object describing the previous and current states

type LifecycleEvent = {
  state: LifecycleState        // The application lifecycle state
  previous: LifecycleState     // The application lifecycle state
  source?: 'voice' | 'remote'  // The source of the lifecycle change.
}

See also:

• LifecycleState