0.5.3-core-Lifecycle

Lifecycle

Article summary

Did you find this summary helpful?

Thank you for your feedback

title: Lifecycle

version: 0.5.3
layout: default
sdk: core

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

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

version: 0.5.3 layout: default sdk: core
# Lifecycle Module
OpenRPC
Table of Contents
Usage
Overview
Events
Methods
Schemas

Lifecycle

version: 0.5.3 layout: default sdk: core

# Lifecycle Module

OpenRPC

Table of Contents

Usage

Overview

Events

inactive

Event value

Promise Resolution

Examples

Request

Response

foreground

Event value

Promise Resolution

Examples

Request

Response

Request

Response

background

Event value

Promise Resolution

Examples

Request

Response

suspended

Event value

Promise Resolution

Examples

Request

Response

unloading

Event value

Promise Resolution

Examples

Request

Response

Methods

ready

Promise Resolution

Examples

close

Parameters

Promise Resolution

Examples

finished

Promise Resolution

Examples

state

Promise Resolution

Examples

Schemas

LifecycleEvent

Details

LifecycleState

Details

CloseReason

Details

What's Next

version: 0.5.3
layout: default
sdk: core