---
title: "Lifecycle"
slug: "170-core-lifecycle"
updated: 2025-12-09T17:11:31Z
published: 2025-12-09T18:02:06Z
canonical: "docs.developer.comcast.com/170-core-lifecycle"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.developer.comcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

**Lifecycle Module 1.7.0 | Core SDK**

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

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | [`CloseReason`](/docs/170-core-Lifecycle-schemas#CloseReason) | true | The reason the app is requesting to be closed values: `'remoteButton' \| 'userExit' \| 'done' \| 'error'` |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

**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'

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

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

#### Examples

Default Example

JavaScript:

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

let results = await Lifecycle.finished()
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
}
```

---

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

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `event` | `string` | Yes | The event to listen for, see [Events](/docs/170-core-lifecycle#events). |
| *callback* | `function` | Yes | A function that will be invoked when the event occurs. |

Promise resolution:

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

Callback parameters:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

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:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| *callback* | `function` | Yes | A function that will be invoked when the event occurs. The event data depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

Callback parameters:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `event` | `string` | Yes | The event that has occured listen for, see [Events](/docs/170-core-lifecycle#events). |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

Promise resolution:

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

See [Listening for events](/docs/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:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `event` | `string` | Yes | The event to listen for, see [Events](/docs/170-core-lifecycle#events). |
| *callback* | `function` | Yes | A function that will be invoked when the event occurs. |

Promise resolution:

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

Callback parameters:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

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:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| *callback* | `function` | Yes | A function that will be invoked when the event occurs. The event data depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

Callback parameters:

| Param | Type | Required | Summary |
| --- | --- | --- | --- |
| `event` | `string` | Yes | The event that has occured listen for, see [Events](/docs/170-core-lifecycle#events). |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](/docs/170-core-lifecycle#events). |

Promise resolution:

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

See [Listening for events](/docs/listening-for-events/) for more information and examples.

### ready

Notify the platform that the app is ready

```
function ready(): Promise<void>
```

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:ready |

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

**JSON-RPC:**

Request:

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

Response:

```
{
  "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](/docs/170-core-Lifecycle-schemas#LifecycleState)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

#### Examples

Default Example

JavaScript:

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

const state = Lifecycle.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"
}
```

---

## Events

### background

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### foreground

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

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

---

### inactive

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### suspended

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### unloading

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

## Private Events

**View**

  

### background

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### foreground

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

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

---

### inactive

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### suspended

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

### unloading

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

See also: [listen()](/docs/170-core-lifecycle#listen), [once()](/docs/170-core-lifecycle#listen), [clear()](/docs/170-core-lifecycle#listen).

Event value:

[LifecycleEvent](/docs/170-core-lifecycle#lifecycleevent)

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:lifecycle:state |

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

---

## 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](/docs/170-core-Lifecycle-schemas#LifecycleState)

---