src/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 have an optional frame with title bar and size controls. They are
  93 not associated with any Chrome browser windows.
  94 </p>
  95
  96 <p>Here's a sample window created from <code>background.js</code>:</p>
  97
  98 <pre data-filename="background.js">
  99 chrome.app.runtime.onLaunched.addListener(function() {
 100   chrome.app.window.create('main.html', {
 101     bounds: {
 102       width: 800,
 103       height: 600,
 104       left: 100,
 105       top: 100
 106     },
 107     minWidth: 800,
 108     minHeight: 600
 109   });
 110 });
 111 </pre>
 112
 113 <h3 id="launch_data">Including Launch Data</h3>
 114
 115 <p>
 116 Depending on how your app is launched,
 117 you may need to handle launch data
 118 in your event page.
 119 By default, there is no launch data
 120 when the app is started by the app launcher.
 121 For apps that have file handlers,
 122 you need to handle the
 123 <code>launchData.items</code> parameter to allow
 124 them to be launched with files.
 125 </p>
 126
 127 <h2 id="runtime">Listening for app runtime events</h2>
 128
 129 <p>
 130 The app runtime controls the app installs, updates, and uninstalls.
 131 You don't need to do anything to set up the app runtime,
 132 but your event page can listen out for the <code>onInstalled()</code> event
 133 to store local settings and the
 134 <code>onSuspend()</code> event to do simple clean-up tasks
 135 before the event page is unloaded.
 136 </p>
 137
 138 <h3 id="local_settings">Storing local settings</h3>
 139
 140 <p>
 141 <code>chrome.runtime.onInstalled()</code>
 142 is called when your app has first been installed,
 143 or when it has been updated.
 144 Any time this function is called,
 145 the <code>onInstalled</code> event is fired.
 146 The event page can listen for this event and use the
 147 <a href="storage.html">Storage API</a>
 148 to store and update local settings
 149 (see also <a href="app_storage.html#options">Storage options</a>).
 150 </p>
 151
 152 <pre data-filename="background.js">
 153 chrome.runtime.onInstalled.addListener(function() {
 154   chrome.storage.local.set(object items, function callback);
 155 });
 156 </pre>
 157
 158 <h3 id="preventing_loss">Preventing data loss</h3>
 159
 160 <p>
 161 Users can uninstall your app at any time.
 162 When uninstalled,
 163 no executing code or private data is left behind.
 164 This can lead to data loss
 165 since the users may be uninstalling an app
 166 that has locally edited, unsynchronized data.
 167 You should stash data to prevent data loss.
 168 </p>
 169
 170 <p>
 171 At a minimum,
 172 you should store user settings
 173 so that if users reinstall your app,
 174 their information is still available for reuse.
 175 Using the Storage API
 176 ($ref:storage.sync),
 177 user data can be automatically synced
 178 with Chrome sync.
 179 </p>
 180
 181 <h3 id="clean-up">Clean-up before app closes</h3>
 182
 183 <p>
 184 The app runtime sends the <code>onSuspend()</code>
 185 event to the event page before unloading it.
 186 Your event page can listen out for this event and
 187 do clean-up tasks before the app closes.
 188 </p>
 189
 190 <p>
 191 Once this event is fired,
 192 the app runtime starts the process of closing the app:
 193 all events stop firing and
 194 JavaScript execution is halted.
 195 Any asynchronous operations started
 196 while handling this event are not guaranteed to complete.
 197 Keep the clean-up tasks synchronous and simple.
 198 </p>
 199
 200 <pre data-filename="background.js">
 201 chrome.runtime.onSuspend.addListener(function() {
 202   // Do some simple clean-up tasks.
 203 });
 204 </pre>
 205
 206 <p class="backtotop"><a href="#top">Back to top</a></p>