Handling the app lifecycle
This guide shows where code goes as the app moves from launch to the background, back to the foreground, and through low memory: building the UI, saving data, releasing caches, keeping the screen on, and passing messages between parts of the app. Everything used here is on the global object application. For details on creating windows, see Creating windows and handling scenes.
Recommended approach
- Put the code that builds the UI in the
sceneconnectcallback, and register the listener at the top level ofmain.js. The runtime finishes executing all ofmain.jsbefore the system creates a scene. Events are not replayed: if you register only after some Promise fulfills, you may already have missed it. - Finish saving data you need to keep in
background. Write it toapplication.storage, whose writes are synchronous. Don't wait forbeforeterminate: it isn't necessarily fired when the app is terminated in the background. - On
memorywarning, drop data you can get again. The runtime doesn't decide what to drop for the app; after the listeners run, it has the JS engine reclaim memory, so objects the listeners let go of are reclaimed then. - Keep app-wide shared data in your module's own variables, not on
application.applicationis an ordinary JS object and you can add properties to it, but the type definitions don't include them, so every read and write needs a cast; andapplicationexists for as long as the app runs, so anything attached to it is never garbage-collected. In particular, don't attach scenes, windows, or view controllers to it.
First app
Start from a blank app: print the app's information, and once the system is ready, create the window and view controller.
// 1. Read the app's information. These are readable as soon as the script starts
console.log('Bundle ID', application.bundleIdentifier);
console.log('Version', application.version, 'Build', application.build);
// 2. There is no scene yet, so the UI can't be built yet
console.log('Scene count', application.scenes.length);
// 3. The system fires sceneconnect once the scene is ready. UI code goes here
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
console.log('UI built, scene count', application.scenes.length);
});Effect
- The console first prints three lines. For an app with bundle ID
com.example.shop:Bundle ID com.example.shopVersion 0.1.0 Build 1Scene count 0
- Then the screen changes from black to the system background color: white in light mode, black in dark mode.
- The console prints
UI built, scene count 1.
This code has not been run as a whole in the simulator. Every API it uses has been run in the acceptance tests.
The callback may run more than once: when the system destroys a scene and recreates it, sceneconnect fires again. Each time, the callback builds the UI from scratch with e.scene; see Create windows and handle scenes.
Read the app's name and version
console.log(application.bundleIdentifier);
console.log(application.version);
console.log(application.build);
console.log(application.info.CFBundleDisplayName);Effect: The console prints the bundle ID, version number, build number, and app name in order, for example com.example.shop, 0.1.0, 1, Shop. These four values come from the project's nacre.config.json. What the app name reads as is not verified in the simulator.
The app's display name has no property of its own; read it from info.
Know when the app goes to the background and returns to the foreground
for (const type of ['inactive', 'background', 'foreground', 'active']) {
application.addEventListener(type, (e) => {
console.log(e.type, 'state now =', application.state);
});
}Effect: When the user goes to the Home Screen and then taps the icon to return to the app, the console prints in order:
inactive state now = activebackground state now = backgroundforeground state now = backgroundactive state now = active
inactive and foreground mean "about to", so state still has the old value when these two events arrive. inactive doesn't fire only before going to the background: it also fires on an incoming call or when Notification Center is pulled down, after which the app may go straight back to active. At launch the app also fires foreground and active in order.
Save data when entering the background
application.addEventListener('background', () => {
application.storage.set('draft', 'Half-written content');
});Effect: Each time the app enters the background, the draft is saved to local storage. If the system later terminates the app, it can be read the next time the app opens.
After the app enters the background, the system suspends it after a short time: JS no longer runs and timers no longer fire. When the user returns, the app resumes where it was suspended, and the variables in JS are all still there. The system may also terminate the app directly in the background, without any notification; the next time it opens, main.js runs from the beginning. These points come from iOS's definitions and are not verified in the simulator. So write what you need to keep to storage in background. There is not yet a way to request more execution time after entering the background.
Release caches on a memory warning
/** @type {Map<string, string>} */
const cache = new Map();
application.addEventListener('memorywarning', () => {
cache.clear();
console.log('Cache cleared');
});Effect: When the system issues a memory warning, the console prints Cache cleared.
To trigger it in the simulator, choose Simulate Memory Warning from the Device menu. What you should drop is data you can get again: cached images, data that has been parsed but can be parsed again, and view controllers that aren't on screen.
Keep the screen on
iOS locks the screen automatically after a period without touches. You can turn this off while playing video or showing a QR code.
application.idleTimerDisabled = true;Effect: While the app is in the foreground, the device no longer locks automatically. Not verified in the simulator.
This setting applies to the whole app and doesn't reset on its own. Set it back to false when leaving the view controller that needs the screen on; otherwise the device never locks while the app is in the foreground, which uses more power.
Read the device's environment settings
console.log(application.layoutDirection);
console.log(application.contentSizeCategory);
console.log(application.backgroundRefreshStatus);
console.log(application.protectedDataAvailable);Effect: The console prints four lines, each the value on the current device. For example, when the system language is written left to right and the text size is the default, the first two lines are ltr and UICTContentSizeCategoryL. The actual values of the last two lines are not verified in the simulator.
Whether it's dark or light, and the screen's scale, are not on application; read them from the traitCollection of a scene or view; see Traits. For the device model and system version, see UIDevice. The system language can't be read yet.
Save data
application has two entry points for storing data, and a third once @nacrejs/keychain is installed:
| Property | What it stores | Documentation |
|---|---|---|
application.storage | Settings and small state. Key-value pairs, read and written synchronously | Local storage |
application.fileSystem | Files. Everything returns a Promise | File system |
application.keychain | Tokens and passwords, stored encrypted. Everything returns a Promise. Install @nacrejs/keychain first; without it, this property doesn't exist | Keychain |
application.storage.set('theme', 'dark');
console.log(application.storage.get('theme'));Effect: The console prints dark. The value is still there after closing and reopening the app.
Pass messages between parts of the app
application can listen for and dispatch events you define. An event name can be any string, as long as it differs from the existing event names. Two parts of the app that don't reference each other can use this to notify each other.
application.addEventListener('login', (e) => {
console.log('Received', e.type);
});
application.dispatchEvent(new Event('login'));Effect: Before dispatchEvent() returns, the console prints Received login.
Events you dispatch yourself are synchronous. To let listeners cancel one, pass { cancelable: true } when constructing it; see dispatchEvent(). If you don't want to go through application, you can also create your own with new EventTarget().
See also
Application: all members ofapplication- Creating windows and handling scenes
- Handling errors in one place
- Handling links that open the app