0.5.3-core-Lifecycle

Lifecycle

Article summary

Did you find this summary helpful?

Thank you for your feedback

Lifecycle Module 0.5.3

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

Events

inactive

Listen to the inactive event

// listen to inactive
Lifecycle.listen('inactive', (data: LifecycleEvent) => void): Promise<bigint>

// listen to inactive once
Lifecycle.once('inactive', (data: LifecycleEvent) => void): Promise<bigint>

// clear a listener
Lifecycle.clear(listenerId?: bigint): void

Event value

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

Promise Resolution

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

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

##### Listen to an event only once

JavaScript

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

Alternately, simply call once():

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

##### Clear all listeners for an event

JavaScript

Lifecycle.clear('inactive')

foreground

Listen to the foreground event

// listen to foreground
Lifecycle.listen('foreground', (data: LifecycleEvent) => void): Promise<bigint>

// listen to foreground once
Lifecycle.once('foreground', (data: LifecycleEvent) => void): Promise<bigint>

// clear a listener
Lifecycle.clear(listenerId?: bigint): void

Event value

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

Promise Resolution

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

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

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

##### Listen to an event only once

JavaScript

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

Alternately, simply call once():

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

##### Clear all listeners for an event

JavaScript

Lifecycle.clear('foreground')

background

Listen to the background event

// listen to background
Lifecycle.listen('background', (data: LifecycleEvent) => void): Promise<bigint>

// listen to background once
Lifecycle.once('background', (data: LifecycleEvent) => void): Promise<bigint>

// clear a listener
Lifecycle.clear(listenerId?: bigint): void

Event value

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

Promise Resolution

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

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

##### Listen to an event only once

JavaScript

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

Alternately, simply call once():

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

##### Clear all listeners for an event

JavaScript

Lifecycle.clear('background')

suspended

Listen to the suspended event

// listen to suspended
Lifecycle.listen('suspended', (data: LifecycleEvent) => void): Promise<bigint>

// listen to suspended once
Lifecycle.once('suspended', (data: LifecycleEvent) => void): Promise<bigint>

// clear a listener
Lifecycle.clear(listenerId?: bigint): void

Event value

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

Promise Resolution

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

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

##### Listen to an event only once

JavaScript

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

Alternately, simply call once():

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

##### Clear all listeners for an event

JavaScript

Lifecycle.clear('suspended')

unloading

Listen to the unloading event

// listen to unloading
Lifecycle.listen('unloading', (data: LifecycleEvent) => void): Promise<bigint>

// listen to unloading once
Lifecycle.once('unloading', (data: LifecycleEvent) => void): Promise<bigint>

// clear a listener
Lifecycle.clear(listenerId?: bigint): void

Event value

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

Promise Resolution

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

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

##### Listen to an event only once

JavaScript

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

Alternately, simply call once():

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

##### Clear all listeners for an event

JavaScript

Lifecycle.clear('unloading')

Methods

ready

Notify the platform that the app is ready

function ready(): Promise<void>

Promise Resolution

Type	Description
`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
}

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

Type	Description
`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
}

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

Type	Description
`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
}

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 '@firebolt-js/sdk'

Lifecycle.state()
    .then(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"
}

Schemas

LifecycleEvent

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

Details

A an object describing the previous and current states

LifecycleState

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

Details

Valid states in the Lifecycle API

CloseReason

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

Details

Reasons for calling the close method

Was this article helpful?

What's Next

Localization

Table of contents

Usage
Overview
Events
Methods
Schemas