NativeScript Core
In this article
Not finding the help you need?
Ask the community Improve this article

Application Management

The application module lets you manage the life cycle of your NativeScript apps from starting the application to storing user-defined settings.

Application Run

The method run from the application module is required to start the application and accepts the path to the root XML file.

Note: You must call the run method of the application module after the module initialization. Any code after the run call will not be executed.

/*
iOS calls UIApplication and triggers the application main event loop.
*/

const application = require("tns-core-modules/application");
application.run({ moduleName: "app-root" });

Note: Prior to version 4.0.0 all NativeScript application had single topmost Frame implicitly created by the application.start() method. With NativeScript 4.x.x and above the root Frame is no longer implicitly created. Instead you can specify any View to be the root of your application while using application.run({ moduleName: "app-root"}) where app-root is the file containing your root View. More about the Frame API and navigation could be found in the navigation article

Use Application Events

NativeScript applications have the following life cycle events.

  • launch: This event is raised when application launch.
  • suspend: This event is raised when the application is suspended.
  • resume: This event is raised when the application is resumed after it has been suspended.
  • displayed: This event is raised when the UIelements are rendered.
  • orientationChanged: This event is raised when the device changes orientation.
  • exit: This event is raised when the application is about to exit.
  • lowMemory: This event is raised when the memory on the target device is low.
  • uncaughtError: This event is raised when an uncaught application error is present.
const application = require("tns-core-modules/application");

application.on(application.launchEvent, (args) => {
    if (args.android) {
        // For Android applications, args.android is an android.content.Intent class.
        console.log("Launched Android application with the following intent: " + args.android + ".");
    } else if (args.ios !== undefined) {
        // For iOS applications, args.ios is NSDictionary (launchOptions).
        console.log("Launched iOS application with options: " + args.ios);
    }
});

application.on(application.suspendEvent, (args) => {
    if (args.android) {
        // For Android applications, args.android is an android activity class.
        console.log("Activity: " + args.android);
    } else if (args.ios) {
        // For iOS applications, args.ios is UIApplication.
        console.log("UIApplication: " + args.ios);
    }
});

application.on(application.resumeEvent, (args) => {
    if (args.android) {
        // For Android applications, args.android is an android activity class.
        console.log("Activity: " + args.android);
    } else if (args.ios) {
        // For iOS applications, args.ios is UIApplication.
        console.log("UIApplication: " + args.ios);
    }
});

application.on(application.displayedEvent, (args) => {
    // args is of type ApplicationEventData
    console.log("displayedEvent");
});

application.on(application.orientationChangedEvent, (args) => {
    // args is of type OrientationChangedEventData
    console.log(args.newValue); // "portrait", "landscape", "unknown"
});


application.on(application.exitEvent, (args) => {
    if (args.android) {
        // For Android applications, args.android is an android activity class.
        console.log("Activity: " + args.android);
        if (args.android.isFinishing()) {
            console.log("Activity: " + args.android + " is exiting");
        } else {
            console.log("Activity: " + args.android + " is restarting");
        }
    } else if (args.ios) {
        // For iOS applications, args.ios is UIApplication.
        console.log("UIApplication: " + args.ios);
    }
});

application.on(application.lowMemoryEvent, (args) => {
    if (args.android) {
        // For Android applications, args.android is an android activity class.
        console.log("Activity: " + args.android);
    } else if (args.ios) {
        // For iOS applications, args.ios is UIApplication.
        console.log("UIApplication: " + args.ios);
    }
});

application.on(application.uncaughtErrorEvent, (args) => {
    console.log("Error: " + args.error);
});

application.run({ moduleName: "app-root" });

Android Activity Events

NativeScript applications have the following Android specific activity events:

  • activityCreated: This event is raised when activity is created.
  • activityDestroyed: This event is raised when activity is destroyed.
  • activityStarted: This event is raised when activity is started.
  • activityPaused: This event is raised when activity is paused.
  • activityResumed: This event is raised when activity is resumed.
  • activityStopped: This event is raised when activity is stopped.
  • saveActivityState: This event is raised to retrieve per-instance state from an activity before being killed so that the state can be restored.
  • activityResult: This event is raised when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it.
  • activityBackPressed: This event is raised when the activity has detected the user's press of the back key.
const application = require("tns-core-modules/application");

if (application.android) {
    application.android.on(application.AndroidApplication.activityCreatedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity + ", Bundle: " + args.bundle);
    });

    application.android.on(application.AndroidApplication.activityDestroyedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
    });

    application.android.on(application.AndroidApplication.activityStartedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
    });

    application.android.on(application.AndroidApplication.activityPausedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
    });

    application.android.on(application.AndroidApplication.activityResumedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
    });

    application.android.on(application.AndroidApplication.activityStoppedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
    });

    application.android.on(application.AndroidApplication.saveActivityStateEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity + ", Bundle: " + args.bundle);
    });

    application.android.on(application.AndroidApplication.activityResultEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity +
            ", requestCode: " + args.requestCode + ", resultCode: " + args.resultCode + ", Intent: " + args.intent);
    });

    application.android.on(application.AndroidApplication.activityBackPressedEvent, function (args) {
        console.log("Event: " + args.eventName + ", Activity: " + args.activity);
        // Set args.cancel = true to cancel back navigation and do something custom.
    });
}

application.run({ moduleName: "app-root" });

iOS UIApplicationDelegate

In NativeScript, you can specify custom UIApplicationDelegate for the iOS application:

const application = require("tns-core-modules/application");
const MyDelegate = (function (_super) {
    __extends(MyDelegate, _super);
    function MyDelegate() {
        _super.apply(this, arguments);
    }
    MyDelegate.prototype.applicationDidFinishLaunchingWithOptions = function (application, launchOptions) {
        console.log("applicationWillFinishLaunchingWithOptions: " + launchOptions);
        return true;
    };
    MyDelegate.prototype.applicationDidBecomeActive = function (application) {
        console.log("applicationDidBecomeActive: " + application);
    };
    MyDelegate.ObjCProtocols = [UIApplicationDelegate];
    return MyDelegate;
})(UIResponder);
application.ios.delegate = MyDelegate;
application.run({ moduleName: "app-root" });

Note: If you’re using TypeScript in your NativeScript apps, you need to install the tns-platform-declarations plugin to add typings for native iOS APIs such as UIApplicationDelegate.

Persist and Restore Application Settings

To persist user-defined settings, you need to use the application-settings module. The application-settings module is a static singleton hash table that stores key-value pairs for the application.

The getter methods have two parameters: a key and an optional default value to return if the specified key does not exist. The setter methods have two required parameters: a key and value. 

const applicationSettings = require("tns-core-modules/application-settings");
// Event handler for Page "loaded" event attached in main-page.xml.
function pageLoaded(args) {
    applicationSettings.setString("Name", "John Doe");
    console.log(applicationSettings.getString("Name")); // Prints "John Doe".
    applicationSettings.setBoolean("Married", false);
    console.log(applicationSettings.getBoolean("Married")); // Prints false.
    applicationSettings.setNumber("Age", 42);
    console.log(applicationSettings.getNumber("Age")); // Prints 42.
    console.log(applicationSettings.hasKey("Name")); // Prints true.
    applicationSettings.remove("Name"); // Removes the Name entry.
    console.log(applicationSettings.hasKey("Name")); // Prints false.
}
exports.pageLoaded = pageLoaded;