Lifecycle Module

Version Lifecycle 1.2.0

Table of Contents

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

Usage

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

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

Overview

Methods and events for responding to lifecycle changes in your app

Methods

close

Request that the platform move your app out of focus

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

Parameters:

Promise resolution:

Capabilities:

Examples

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

JavaScript:

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

let success = await Lifecycle.close('remoteButton')
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
}

Close the app when the user selects an exit menu item

JavaScript:

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

let success = await Lifecycle.close('userExit')
console.log(success)

Value of 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:

Capabilities:

Examples

Default Example

JavaScript:

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

let results = await Lifecycle.finished()
console.log(results)

Value of results:

null

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

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

listen

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

listen(event: string, callback: (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:

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

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

once

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

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

The once method will only pass the next instance of this event, and then dicard the listener you provided.

Parameters:

Promise resolution:

Callback parameters:

To listen to the next instance only of any events from this module pass only a callback, without specifying an event name:

once(callback: (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:

Capabilities:

Examples

Let the platform know that your app is ready

JavaScript:

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

let result = await Lifecycle.ready()
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(): Promise<LifecycleState>

Promise resolution:

LifecycleState

Capabilities:

Examples

Default Example

JavaScript:

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

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

function listen('background', () => void): Promise<number>

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

Event value:

LifecycleEvent

Capabilities:

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

function listen('foreground', () => void): Promise<number>

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

Event value:

LifecycleEvent

Capabilities:

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"
  }
}

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"
}

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

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

inactive

function listen('inactive', () => void): Promise<number>

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

Event value:

LifecycleEvent

Capabilities:

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

function listen('suspended', () => void): Promise<number>

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

Event value:

LifecycleEvent

Capabilities:

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

function listen('unloading', () => void): Promise<number>

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

Event value:

LifecycleEvent

Capabilities:

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"
  }
}

Types

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