| <meta name="doc-family" content="apps"> |
| <h1>Chrome App Lifecycle</h1> |
| |
| |
| <p> |
| The app runtime and event page are responsible |
| for managing the app lifecycle. |
| The app runtime manages app installation, |
| controls the event page, |
| and can shutdown the app at anytime. |
| The event page listens out for events from the app runtime |
| and manages what gets launched and how. |
| </p> |
| |
| <h2 id="lifecycle">How the lifecycle works</h2> |
| |
| <p> |
| The app runtime loads the event page |
| from a user's desktop and |
| the <code>onLaunch()</code> event is fired. |
| This event tells the event page what windows |
| to launch and their dimensions. |
| The lifecycle diagram here isn't the nicest to look at, |
| but it's practical (and we will make it nicer soon). |
| </p> |
| |
| <img src="{{static}}/images/applifecycle.png" |
| width="444" |
| height="329" |
| alt="how app lifecycle works"> |
| |
| <p> |
| When the event page has no executing JavaScript, |
| no pending callbacks, and no open windows, |
| the runtime unloads the event page and closes the app. |
| Before unloading the event page, |
| the <code>onSuspend()</code> event is fired. |
| This gives the event page opportunity |
| to do simple clean-up tasks |
| before the app is closed. |
| </p> |
| |
| <h2 id="eventpage">Create event page and windows</h2> |
| |
| <p> |
| All apps must have an event page. |
| This page contains the top-level logic of the application |
| with none of its own UI and is responsible |
| for creating the windows for all other app pages. |
| </p> |
| |
| <h3 id="create_event_page">Create event page</h3> |
| |
| <p> |
| To create the event page, |
| include the "background" field in the app manifest |
| and include the <code>background.js</code> in the scripts array. |
| Any library scripts used by the event page need to be added |
| to the "background" field first: |
| </p> |
| |
| <pre data-filename="manifest.json"> |
| "background": { |
| "scripts": [ |
| "foo.js", |
| "background.js" |
| ] |
| } |
| </pre> |
| |
| <p> |
| Your event page must include the <code>onLaunched()</code> function. |
| This function is called |
| when your application is launched in any way: |
| </p> |
| |
| <pre data-filename="background.js"> |
| chrome.app.runtime.onLaunched.addListener(function() { |
| // Tell your app what to launch and how. |
| }); |
| </pre> |
| |
| <h3 id="create_windows">Create windows</h3> |
| |
| <p> |
| An event page may create one or more windows at its discretion. |
| By default, these windows are created with a script connection |
| to the event page and are directly scriptable by the event page. |
| </p> |
| |
| <p> |
| Windows have an optional frame with title bar and size controls. They are |
| not associated with any Chrome browser windows. |
| </p> |
| |
| <p>Here's a sample window created from <code>background.js</code>:</p> |
| |
| <pre data-filename="background.js"> |
| chrome.app.runtime.onLaunched.addListener(function() { |
| chrome.app.window.create('main.html', { |
| bounds: { |
| width: 800, |
| height: 600, |
| left: 100, |
| top: 100 |
| }, |
| minWidth: 800, |
| minHeight: 600 |
| }); |
| }); |
| </pre> |
| |
| <h3 id="launch_data">Including Launch Data</h3> |
| |
| <p> |
| Depending on how your app is launched, |
| you may need to handle launch data |
| in your event page. |
| By default, there is no launch data |
| when the app is started by the app launcher. |
| For apps that have file handlers, |
| you need to handle the |
| <code>launchData.items</code> parameter to allow |
| them to be launched with files. |
| </p> |
| |
| <h2 id="runtime">Listening for app runtime events</h2> |
| |
| <p> |
| The app runtime controls the app installs, updates, and uninstalls. |
| You don't need to do anything to set up the app runtime, |
| but your event page can listen out for the <code>onInstalled()</code> event |
| to store local settings and the |
| <code>onSuspend()</code> event to do simple clean-up tasks |
| before the event page is unloaded. |
| </p> |
| |
| <h3 id="local_settings">Storing local settings</h3> |
| |
| <p> |
| <code>chrome.runtime.onInstalled()</code> |
| is called when your app has first been installed, |
| or when it has been updated. |
| Any time this function is called, |
| the <code>onInstalled</code> event is fired. |
| The event page can listen for this event and use the |
| <a href="storage.html">Storage API</a> |
| to store and update local settings |
| (see also <a href="app_storage.html#options">Storage options</a>). |
| </p> |
| |
| <pre data-filename="background.js"> |
| chrome.runtime.onInstalled.addListener(function() { |
| chrome.storage.local.set(object items, function callback); |
| }); |
| </pre> |
| |
| <h3 id="preventing_loss">Preventing data loss</h3> |
| |
| <p> |
| Users can uninstall your app at any time. |
| When uninstalled, |
| no executing code or private data is left behind. |
| This can lead to data loss |
| since the users may be uninstalling an app |
| that has locally edited, unsynchronized data. |
| You should stash data to prevent data loss. |
| </p> |
| |
| <p> |
| At a minimum, |
| you should store user settings |
| so that if users reinstall your app, |
| their information is still available for reuse. |
| Using the Storage API |
| ($ref:storage.sync), |
| user data can be automatically synced |
| with Chrome sync. |
| </p> |
| |
| <h3 id="clean-up">Clean-up before app closes</h3> |
| |
| <p> |
| The app runtime sends the <code>onSuspend()</code> |
| event to the event page before unloading it. |
| Your event page can listen out for this event and |
| do clean-up tasks before the app closes. |
| </p> |
| |
| <p> |
| Once this event is fired, |
| the app runtime starts the process of closing the app: |
| all events stop firing and |
| JavaScript execution is halted. |
| Any asynchronous operations started |
| while handling this event are not guaranteed to complete. |
| Keep the clean-up tasks synchronous and simple. |
| </p> |
| |
| <pre data-filename="background.js"> |
| chrome.runtime.onSuspend.addListener(function() { |
| // Do some simple clean-up tasks. |
| }); |
| </pre> |
| |
| <p class="backtotop"><a href="#top">Back to top</a></p> |