Monitor the application lifecycle from JS

The lifecycle of an app is the time from when your app starts to the time it terminates. During this time the app will go through a number of states.

The Lifecycle module allows you query the current state and also be alerted when the app changes state.

The States

  • Starting
  • Background
  • Foreground
  • Interactive
Starting

Your app start event is implicit, as this is when your JavaScript is first evaluated.

Background

Your app is not the app the user is interactive with right now and so the operating system has put it into a 'sleep' state.

Whilst your app is in this state is is not allowed to run code, but you don't have to worry about this as Fuse will ensure your JS/UX is not doing something when it shouldn't.

Foreground

Your app is front and center on the user's device but they cannot yet interact with it. The main reason to be in this state is that the user has opened the notification bar on iOS or Android.

Interactive

Your app is now in the foreground and is accepting input from the user.

Changing States

It would be hard to work with app lifecycle if your app could just jump around the states randomly. Instead we guarentee the following flow through the states:

Starting ↓ Background ⟷ Foreground ⟷ Interactive ↓ Terminating

No terminating event

You may be wondering why there is no terminating event. The reason is that on mobile platforms the OS doesn't promise to call you when terminating your app. It may, but in certain circumstances (low memory, emergency phone call, etc) it won't.

Because of this the guides for mobile platforms strongly advise against using the terminating event as a cue that the app is shutting down, instead you should be regularly 'checkpointing' your app so you can recover from any kind of shutdown.

Given that we are not meant to use it, we have opted not to expose the event.

This module is an EventEmitter, so the methods from EventEmitter can be used to listen to events.

Example

<JavaScript>
    var Lifecycle = require('FuseJS/Lifecycle');

    Lifecycle.on("enteringForeground", function() {
        console.log("on enteringForeground");
    });
    Lifecycle.on("enteringInteractive", function() {
        console.log("on enteringInteractive");
    });
    Lifecycle.on("exitedInteractive", function() {
        console.log("on exitedInteractive");
    });
    Lifecycle.on("enteringBackground", function() {
        console.log("on enteringBackground");
    });
    Lifecycle.on("stateChanged", function(newState) {
        console.log("on stateChanged " + newState);
    });
    module.exports = { lifecycleState: Lifecycle.observe("stateChanged") }
</JavaScript>
<StackPanel>
    <Text TextWrapping="Wrap">Open the Fuse Monitor to see the logs</Text>
    <Text>Current lifecycle state:</Text>
    <Text Value="{lifecycleState}" />
</StackPanel>

In the above example we're using the EventEmitter on method to listen to the different events. We're also using the EventEmitter observe method on the "stateChanged" event to get an Observable containing the current state.

Location

Namespace
FuseJS
Package
FuseJS 2.9.1
Show Uno properties and methods

Interface of Lifecycle

state : int js

Will give you the current state as an integer

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/getcurrentstate.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>
enteringBackground js

Triggered when the app is leaving the running state and is about to be suspended.

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/onenteringbackground_1c7eb6b7.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>
enteringForeground js

Triggered when the app has left the suspended state and now is running. You will receive this event when the app starts.

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/onenteringforeground_1c7eb6b7.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>
enteringInteractive js

Triggered when the app is entering a state where it is fully focused and receiving events.

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/onenteringinteractive_1c7eb6b7.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>
exitedInteractive js

Triggered when the app is partially obscured or is no longer the focus (e.g. when you drag open the notification bar)

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/onexitedinteractive_1c7eb6b7.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>
stateChanged js

Triggered when the app's lifecycle state has changed.

var Lifecycle = require("FuseJS/Lifecycle"); <a href="../fusejs/lifecycle/onstatechanged_1c7eb6b7.html" class="table-of-contents-item-has-more" title="There is more information available for this entry"><i class="fa fa-ellipsis-h"></i></a>

Inherited from NativeEventEmitterModule

Emit(object[]) uno

Call emit with the given arguments on the underlying JS EventEmitter.

Inherited from NativeModule

Inherited from Module

GetFile : FileSource uno

Returns the file source that will be watched by the Context for changes in Fuse preview. Override in subclasses and return correct file source to support live updates in Fuse preview.

Inherited from object

Implemented Interfaces