Version: 0.5.3

Lifecycle Module

Version 0.5.3

OpenRPC

This document was generated from an OpenRPC JSON-Schema, and is intended to provide a human readable overview and examples of the methods contained in the module.

For the full schema, see the link below.

Schema
lifecycle.json

Usage
Overview
Events
Methods
Schemas

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
}

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

Lifecycle Module

OpenRPC​

Table of Contents​

Usage​

Overview​

Events​

inactive​

Event value​

Promise Resolution​

Examples​

Default Example​

Request

Response

Listen to an event only once​

Clear all listeners for an event​

foreground​

Event value​

Promise Resolution​

Examples​

Default Example​

Request

Response

Move to foreground via remote branded buton​

Request

Response

Listen to an event only once​

Clear all listeners for an event​

background​

Event value​

Promise Resolution​

Examples​

Default Example​

Request

Response

Listen to an event only once​

Clear all listeners for an event​

suspended​

Event value​

Promise Resolution​

Examples​

Default Example​

Request

Response

Listen to an event only once​

Clear all listeners for an event​

unloading​

Event value​

Promise Resolution​

Examples​

Default Example​

Request

Response

Listen to an event only once​

Clear all listeners for an event​

Methods​

ready​

Promise Resolution​

Examples​

Let the platform know that your app is ready​

Request​

Response​

close​

Parameters​

Promise Resolution​

Examples​

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

Request​

Response​

Close the app when the user selects an exit menu item​

Request​

Response​

finished​

Promise Resolution​

Examples​

Default Example​

Request​

Response​

state​

Promise Resolution​

Examples​

OpenRPC

Table of Contents

Usage

Overview

Events

inactive

Event value

Promise Resolution

Examples

Default Example

Listen to an event only once

Clear all listeners for an event

foreground

Event value

Promise Resolution

Examples

Default Example

Move to foreground via remote branded buton

Listen to an event only once

Clear all listeners for an event

background

Event value

Promise Resolution

Examples

Default Example

Listen to an event only once

Clear all listeners for an event

suspended

Event value

Promise Resolution

Examples

Default Example

Listen to an event only once

Clear all listeners for an event

unloading

Event value

Promise Resolution

Examples

Default Example

Listen to an event only once

Clear all listeners for an event

Methods

ready

Promise Resolution

Examples

Let the platform know that your app is ready

Request

Response

close

Parameters

Promise Resolution

Examples

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

Request

Response

Close the app when the user selects an exit menu item

Request

Response

finished

Promise Resolution

Examples

Default Example

Request

Response

state

Promise Resolution

Examples

Default Example

Request

Response

Schemas

LifecycleEvent

Details

LifecycleState

Details

CloseReason

Details