xref: /external/chromium_org/chrome/common/extensions/docs/templates/articles/app_lifecycle.html

<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 in Chrome Apps are not associated with any Chrome browser
windows. They have an optional frame with title bar and size controls,
and a recommended window ID.
Windows without IDs will not restore to their size and location after restart.
</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', {
    id: 'MyWindowID',
    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">Storage API</a>
to store and update local settings
(see also <a href="app_storage#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>