chrome/common/extensions/docs/templates/articles/app_lifecycle.html

   1 <meta name="doc-family" content="apps">
   2 <h1>Chrome App Lifecycle</h1>
   3
   4
   5 <p>
   6 The app runtime and event page are responsible
   7 for managing the app lifecycle.
   8 The app runtime manages app installation,
   9 controls the event page,
  10 and can shutdown the app at anytime.
  11 The event page listens out for events from the app runtime
  12 and manages what gets launched and how.
  13 </p>
  14
  15 <h2 id="lifecycle">How the lifecycle works</h2>
  16
  17 <p>
  18 The app runtime loads the event page
  19 from a user's desktop and
  20 the <code>onLaunch()</code> event is fired.
  21 This event tells the event page what windows
  22 to launch and their dimensions.
  23 The lifecycle diagram here isn't the nicest to look at,
  24 but it's practical (and we will make it nicer soon).
  25 </p>
  26
  27 <img src="{{static}}/images/applifecycle.png"
  28      width="444"
  29      height="329"
  30      alt="how app lifecycle works">
  31
  32 <p>
  33 When the event page has no executing JavaScript,
  34 no pending callbacks, and no open windows,
  35 the runtime unloads the event page and closes the app.
  36 Before unloading the event page,
  37 the <code>onSuspend()</code> event is fired.
  38 This gives the event page opportunity
  39 to do simple clean-up tasks
  40 before the app is closed.
  41 </p>
  42
  43 <h2 id="eventpage">Create event page and windows</h2>
  44
  45 <p>
  46 All apps must have an event page.
  47 This page contains the top-level logic of the application
  48 with none of its own UI and is responsible
  49 for creating the windows for all other app pages.
  50 </p>
  51
  52 <h3 id="create_event_page">Create event page</h3>
  53
  54 <p>
  55 To create the event page,
  56 include the "background" field in the app manifest
  57 and include the <code>background.js</code> in the scripts array.
  58 Any library scripts used by the event page need to be added
  59 to the "background" field first:
  60 </p>
  61
  62 <pre data-filename="manifest.json">
  63 "background": {
  64   "scripts": [
  65     "foo.js",
  66     "background.js"
  67   ]
  68 }
  69 </pre>
  70
  71 <p>
  72 Your event page must include the <code>onLaunched()</code> function.
  73 This function is called
  74 when your application is launched in any way:
  75 </p>
  76
  77 <pre data-filename="background.js">
  78 chrome.app.runtime.onLaunched.addListener(function() {
  79   // Tell your app what to launch and how.
  80 });
  81 </pre>
  82
  83 <h3 id="create_windows">Create windows</h3>
  84
  85 <p>
  86 An event page may create one or more windows at its discretion.
  87 By default, these windows are created with a script connection
  88 to the event page and are directly scriptable by the event page.
  89 </p>
  90
  91 <p>
  92 Windows in Chrome Apps are not associated with any Chrome browser
  93 windows. They have an optional frame with title bar and size controls,
  94 and a recommended window ID.
  95 Windows without IDs will not restore to their size and location after restart.
  96 </p>
  97
  98 <p>Here's a sample window created from <code>background.js</code>:</p>
  99
 100 <pre data-filename="background.js">
 101 chrome.app.runtime.onLaunched.addListener(function() {
 102   chrome.app.window.create('main.html', {
 103     id: 'MyWindowID',
 104     bounds: {
 105       width: 800,
 106       height: 600,
 107       left: 100,
 108       top: 100
 109     },
 110     minWidth: 800,
 111     minHeight: 600
 112   });
 113 });
 114 </pre>
 115
 116 <h3 id="launch_data">Including Launch Data</h3>
 117
 118 <p>
 119 Depending on how your app is launched,
 120 you may need to handle launch data
 121 in your event page.
 122 By default, there is no launch data
 123 when the app is started by the app launcher.
 124 For apps that have file handlers,
 125 you need to handle the
 126 <code>launchData.items</code> parameter to allow
 127 them to be launched with files.
 128 </p>
 129
 130 <h2 id="runtime">Listening for app runtime events</h2>
 131
 132 <p>
 133 The app runtime controls the app installs, updates, and uninstalls.
 134 You don't need to do anything to set up the app runtime,
 135 but your event page can listen out for the <code>onInstalled()</code> event
 136 to store local settings and the
 137 <code>onSuspend()</code> event to do simple clean-up tasks
 138 before the event page is unloaded.
 139 </p>
 140
 141 <h3 id="local_settings">Storing local settings</h3>
 142
 143 <p>
 144 <code>chrome.runtime.onInstalled()</code>
 145 is called when your app has first been installed,
 146 or when it has been updated.
 147 Any time this function is called,
 148 the <code>onInstalled</code> event is fired.
 149 The event page can listen for this event and use the
 150 <a href="storage">Storage API</a>
 151 to store and update local settings
 152 (see also <a href="app_storage#options">Storage options</a>).
 153 </p>
 154
 155 <pre data-filename="background.js">
 156 chrome.runtime.onInstalled.addListener(function() {
 157   chrome.storage.local.set(object items, function callback);
 158 });
 159 </pre>
 160
 161 <h3 id="preventing_loss">Preventing data loss</h3>
 162
 163 <p>
 164 Users can uninstall your app at any time.
 165 When uninstalled,
 166 no executing code or private data is left behind.
 167 This can lead to data loss
 168 since the users may be uninstalling an app
 169 that has locally edited, unsynchronized data.
 170 You should stash data to prevent data loss.
 171 </p>
 172
 173 <p>
 174 At a minimum,
 175 you should store user settings
 176 so that if users reinstall your app,
 177 their information is still available for reuse.
 178 Using the Storage API
 179 ($(ref:storage.sync)),
 180 user data can be automatically synced
 181 with Chrome sync.
 182 </p>
 183
 184 <h3 id="clean-up">Clean-up before app closes</h3>
 185
 186 <p>
 187 The app runtime sends the <code>onSuspend()</code>
 188 event to the event page before unloading it.
 189 Your event page can listen out for this event and
 190 do clean-up tasks and save state before the app closes.
 191 </p>
 192
 193 <p>
 194 Once this event is fired,
 195 the app runtime starts the process of closing the app. If the app has open
 196 windows it may be restarted in the future via the <code>onRestarted</code>
 197 event. In this case the app should save its current state to persistent
 198 storage so it can restart in the same state if it receives an
 199 <code>onRestarted</code> event. The app only has a few seconds to save its
 200 state, after which it will be terminated, so it is a good idea to be
 201 incrementally saving app state while the app is running normally.
 202 </p>
 203 <p>
 204 After receiving <code>onSuspend</code> no further events will be delivered
 205 to the app, unless the suspension is aborted for some reason. In this case
 206 the <code>onSuspendCanceled</code> will be delivered to the app, and the app
 207 won't be unloaded.
 208 </p>
 209
 210 <pre data-filename="background.js">
 211 chrome.runtime.onSuspend.addListener(function() {
 212   // Do some simple clean-up tasks.
 213 });
 214 </pre>
 215
 216 <p class="backtotop"><a href="#top">Back to top</a></p>