Version: 0.8.0

Lifecycle Module

Version 0.8.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.

Overview
OpenRPC
Usage
Methods
Events

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:

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

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
`number`	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<number>

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
`number`	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<number>

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
`number`	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<number>

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
`number`	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`	The application lifecycle state

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        // The application lifecycle state
  previous: LifecycleState     // The application lifecycle state
  source?: 'voice' | 'remote'  // The source of the lifecycle change.
}

Lifecycle Module

Overview​

OpenRPC​

Table of Contents​

Usage​

Methods​

close​

finished​

listen​

once​

ready​

state​

Events​

background​

foreground​

inactive​

suspended​

unloading​

Schemas​

LifecycleEvent​

Overview

OpenRPC

Table of Contents

Usage

Methods

close

finished

listen

once

ready

state

Events

background

foreground

inactive

suspended

unloading

Schemas

LifecycleEvent