Lifecycle Module


Version 0.7.0

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

 

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:

Param Type Required Summary
reason CloseReason true The reason the app is requesting to be closed

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

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
More examples… Close the app when the user selects an exit menu item

JavaScript:

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

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

Value of success:

null
JSON-RPC:

Request:

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

Response:

{
  "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
JSON-RPC:

Request:

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

Response:

{
  "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<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Lifecycle.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

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

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Lifecycle.clear(id)

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

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Lifecycle.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

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

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Lifecycle.clear(id)

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

Request:

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

Response:

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

state

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

function state(): LifecycleState

Promise resolution:

Type Description
LifecycleState Valid states in the Lifecycle API

Examples

Default Example

JavaScript:

import { Lifecycle } from ''

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

Value of state:

"foreground"
JSON-RPC:

Request:

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

Response:

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

Events

background

Listen to the background event

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

Event value:

Type Description
LifecycleEvent A an object describing the previous and current states

Examples

Default Example:

JavaScript:

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

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

Value of value

{
  "state": "background",
  "previous": "foreground"
}
JSON-RPC:

Request:

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

Response:

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

foreground

Listen to the foreground event

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

Event value:

Type Description
LifecycleEvent A an object describing the previous and current states

Examples

Default Example:

JavaScript:

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

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

Value of value

{
  "state": "foreground",
  "previous": "inactive"
}
JSON-RPC:

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "foreground",
    "previous": "inactive"
  }
}
More examples… Move to foreground via remote branded buton:

JavaScript:

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

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

Value of value

{
  "state": "foreground",
  "previous": "inactive",
  "source": "remote"
}
JSON-RPC:

Request:

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

Response:

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

Type Description
LifecycleEvent A an object describing the previous and current states

Examples

Default Example:

JavaScript:

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

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

Value of value

{
  "state": "inactive",
  "previous": "initializing"
}
JSON-RPC:

Request:

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

Response:

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

suspended

Listen to the suspended event

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

Event value:

Type Description
LifecycleEvent A an object describing the previous and current states

Examples

Default Example:

JavaScript:

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

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

Value of value

{
  "state": "suspended",
  "previous": "inactive"
}
JSON-RPC:

Request:

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

Response:

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

unloading

Listen to the unloading event

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

Event value:

Type Description
LifecycleEvent A an object describing the previous and current states

Examples

Default Example:

JavaScript:

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

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

Value of value

{
  "state": "unloading",
  "previous": "inactive"
}
JSON-RPC:

Request:

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

Response:

{
  "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        // Valid states in the `Lifecycle` API
  previous: LifecycleState     // Valid states in the `Lifecycle` API
  source?: 'voice' | 'remote'  // The source of the lifecycle change.
}

LifecycleState

Valid states in the Lifecycle API

type LifecycleState = 'initializing' | 'inactive' | 'background' | 'foreground' | 'suspended' | 'unloading'

CloseReason

Reasons for calling the close method

type CloseReason = 'remoteButton' | 'userExit' | 'error'

Go To Top