title: Lifecycle

version: 0.15.0
layout: default
sdk: core

# Lifecycle Module

Version Lifecycle 0.15.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:

void

Capabilities:

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
}

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

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

Capabilities:

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

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:

void

Capabilities:

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:

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', (LifecycleEvent) => 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', (LifecycleEvent) => 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', (LifecycleEvent) => 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', (LifecycleEvent) => 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', (LifecycleEvent) => 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:

'initializing' | 'inactive' | 'foreground' | 'background' | 'unloading' | 'suspended'