chrome/common/extensions/docs/apps/app_lifecycle.html

   1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
   2     1) The <head> information in this page is significant, should be uniform
   3        across api docs and should be edited only with knowledge of the
   4        templating mechanism.
   5     3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
   6        browser, it will be re-generated from the template, json schema and
   7        authored overview content.
   8     4) The <body>.innerHTML is also generated by an offline step so that this
   9        page may easily be indexed by search engines.
  10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
  11     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  12     <link href="../css/print.css" rel="stylesheet" type="text/css" media="print">
  13     <script type="text/javascript" src="../../../../third_party/jstemplate/jstemplate_compiled.js">
  14     </script>
  15     <script type="text/javascript" src="../../../../../third_party/json_minify/minify-sans-regexp.js">
  16     </script>
  17     <script type="text/javascript" src="../js/api_page_generator.js"></script>
  18     <script type="text/javascript" src="../js/bootstrap.js"></script>
  19     <script type="text/javascript" src="../js/sidebar.js"></script>
  20   <title>Manage App Lifecycle - Google Chrome Extensions - Google Code</title></head>
  21   <body doc-family="apps">  <link href="../css/ApiRefStyles.css" rel="stylesheet" type="text/css">
  22   <link href="../css/prettify.css" rel="stylesheet" type="text/css">
  23   <link href="../css/shared.css" rel="stylesheet" type="text/css">
  24   <div id="devModeWarning" class="displayModeWarning">
  25     You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
  26   </div>
  27   <div id="branchWarning" class="displayModeWarning">
  28     <span>WARNING: This is the <span id="branchName">BETA</span> documentation.
  29     It may not work with the stable release of Chrome.</span>
  30     <select id="branchChooser">
  31       <option>Choose a different version...
  32       </option><option value="">Stable
  33       </option><option value="beta">Beta
  34       </option><option value="dev">Dev
  35       </option><option value="trunk">Trunk
  36     </option></select>
  37   </div>
  38   <div id="unofficialWarning" class="displayModeWarning">
  39     <span>WARNING: This is unofficial documentation. It may not work with the
  40     current release of Chrome.</span>
  41     <button id="goToOfficialDocs">Go to the official docs</button>
  42   </div>
  43   <div id="gc-container" class="labs">
  44       <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
  45       <!-- In particular, sub-templates that recurse, must be used by allowing
  46            jstemplate to make a copy of the template in this section which
  47            are not operated on by way of the jsskip="true" -->
  48        <!-- /SUBTEMPLATES -->
  49   <a id="top"></a>
  50     <div id="skipto">
  51       <a href="#gc-pagecontent">Skip to page content</a>
  52       <a href="#gc-toc">Skip to main navigation</a>
  53     </div>
  54     <!-- API HEADER -->
  55     <table id="header" width="100%" cellspacing="0" border="0">
  56       <tbody><tr>
  57         <td valign="middle"><a href="http://code.google.com/"><img src="../images/chrome_logo.gif" alt="Google Code" style="border:0; margin:0;"></a></td>
  58         <td valign="middle" width="100%" style="padding-left:0.6em;">
  59           <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em">
  60             <div id="gsc-search-box">
  61               <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno">
  62               <input type="hidden" name="ie" value="UTF-8">
  63               <input id="gsc-search-input" type="text" name="q" value="" size="55">
  64               <button class="gsc-search-button" type="submit" name="sa">
  65                 <img class="gsc-search-button-lens" src="../images/search.png" alt="Search">
  66               </button>
  67               <br>
  68               <span class="greytext">e.g. "event page" or "alarms"</span>
  69             </div>
  70           </form>
  71           <script type="text/javascript" src="https://www.google.com/jsapi"></script>
  72           <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>
  73           <script type="text/javascript" src="https://www.google.com/coop/cse/t13n?form=cse&amp;t13n_langs=en"></script>
  74           <script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&amp;lang=en"></script>
  75         </td>
  76       </tr>
  77     </tbody></table>
  78     <div id="codesiteContent" class="">
  79       <a id="gc-topnav-anchor"></a>
  80       <div id="gc-topnav">
  81         <h1>Packaged Apps</h1>
  82         <ul id="home" class="gc-topnav-tabs">
  83           <li id="home_link">
  84             <a href="about_apps.html" title="Packaged Apps home page"><span>Home</span></a>
  85           </li>
  86           <li id="docs_link">
  87             <a href="develop_apps.html" title="Packaged apps developer documentation"><span>Docs</span></a>
  88           </li>
  89           <li id="samples_link">
  90             <a href="https://github.com/GoogleChrome/chrome-app-samples" title="Packaged apps samples repository"><span>Samples</span></a>
  91           </li>
  92           <li id="group_link">
  93             <a href="http://groups.google.com/a/chromium.org/group/chromium-apps" title="Google Chrome Apps developer forum"><span>Group</span></a>
  94           </li>
  95           <li id="so_link">
  96             <a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow"><span>Questions?</span></a>
  97           </li>
  98         </ul>
  99       </div> <!-- end gc-topnav -->
 100     <div class="g-section g-tpl-170">
 101       <!-- SIDENAV -->
 102       <div class="g-unit g-first" id="gc-toc">
 103         <ul>
 104           <li><h2>Getting Started</h2>
 105             <ul>
 106               <li><a href="about_apps.html">What Are Packaged Apps?</a></li>
 107               <li><a href="app_architecture.html">Understand the Architecture</a></li>
 108               <li><a href="first_app.html">Create Your First App</a></li>
 109             </ul>
 110           </li>
 111           <li><h2>Developing</h2>
 112             <ul>
 113               <li><a href="develop_apps.html">Before You Start</a></li>
 114               <li><span>The Fundamentals</span>
 115                 <ul>
 116                   <li class="leftNavSelected">Manage App Lifecycle</li>
 117                   <li><a href="app_storage.html">Manage Data</a></li>
 118                   <li><a href="offline_apps.html">Offline First</a></li>
 119                   <li><a href="app_external.html">Embed Content</a></li>
 120                 </ul>
 121               </li>
 122               <li><span>Security &amp; Privacy</span>
 123                 <ul>
 124                   <li><a href="app_identity.html">Identify User</a></li>
 125                   <li><a href="app_csp.html">Comply with CSP</a></li>
 126                 </ul>
 127               </li>
 128               <li><span>Advanced Technologies</span>
 129                 <ul>
 130                   <li><a href="app_network.html">Network Communications</a></li>
 131                   <li><a href="app_hardware.html">Access Hardware Devices</a></li>
 132                   <li><a href="app_intents.html">Connect Apps with Web Intents</a></li>
 133                 </ul>
 134               </li>
 135               <li><a href="app_frameworks.html">MVC Architecture</a></li>
 136             </ul>
 137           </li>
 138           <li><h2>Deploying</h2>
 139             <ul>
 140               <li><a href="publish_app.html">Publish</a></li>
 141             </ul>
 142           </li>
 143           <li><h2>Reference</h2>
 144             <ul>
 145               <li><a href="manifest.html">Manifest Files</a></li>
 146               <li><a href="api_index.html">Chrome JavaScript APIs</a></li>
 147               <li><a href="api_other.html">Supported Libraries</a></li>
 148               <li><a href="app_deprecated.html">Disabled Web Features</a></li>
 149             </ul>
 150           </li>
 151           <li><h2><a href="https://github.com/GoogleChrome/chrome-app-samples">Samples</a></h2></li>
 152           <li><h2><a href="app_known_issues.html">Known Issues</a></h2></li>
 153         </ul>
 154       </div>
 155       <script>
 156         initToggles();
 157       </script>
 158     <div class="g-unit" id="gc-pagecontent">
 159       <div id="pageTitle">
 160         <h1 class="page_title">Manage App Lifecycle</h1>
 161       </div>
 162         <!-- TABLE OF CONTENTS -->
 163         <div id="toc">
 164           <h2>Contents</h2>
 165           <ol>
 166             <li>
 167               <a href="#lifecycle">How the lifecycle works</a>
 168               <ol>
 169               </ol>
 170             </li><li>
 171               <a href="#eventpage">Create event page and windows</a>
 172               <ol>
 173                 <li>
 174                   <a href="#H3-2">Create event page</a>
 175                 </li><li>
 176                   <a href="#H3-3">Create windows</a>
 177                 </li><li>
 178                   <a href="#H3-4">Including Launch Data</a>
 179                 </li>
 180               </ol>
 181             </li><li>
 182               <a href="#runtime">Listening for app runtime events</a>
 183               <ol>
 184                 <li>
 185                   <a href="#H3-6">Storing local settings</a>
 186                 </li><li>
 187                   <a href="#H3-7">Preventing data loss</a>
 188                 </li><li>
 189                   <a href="#H3-8">Clean-up before app closes</a>
 190                 </li>
 191               </ol>
 192             </li>
 193           </ol>
 194         </div>
 195         <!-- /TABLE OF CONTENTS -->
 196         <!-- Standard content lead-in for experimental API pages -->
 197         <!-- STATIC CONTENT PLACEHOLDER -->
 198         <div id="static"><meta name="doc-family" content="apps">
 199 <div id="pageData-name" class="pageData">Manage App Lifecycle</div>
 200 <div id="pageData-showTOC" class="pageData">true</div>
 201 <p>
 202 The app runtime and event page are responsible
 203 for managing the app lifecycle.
 204 The app runtime manages app installation,
 205 controls the event page,
 206 and can shutdown the app at anytime.
 207 The event page listens out for events from the app runtime
 208 and manages what gets launched and how.
 209 </p>
 210 <h2 id="lifecycle">How the lifecycle works</h2>
 211 <p>
 212 The app runtime loads the event page
 213 from a user's desktop and
 214 the <code>onLaunch()</code> event is fired.
 215 This event tells the event page what windows
 216 to launch and their dimensions.
 217 The lifecycle diagram here isn't the nicest to look at,
 218 but it's practical (and we will make it nicer soon).
 219 </p>
 220 <img src="../images/applifecycle.png" width="444" height="329" alt="how app lifecycle works">
 221 <p>
 222 When the event page has no executing JavaScript,
 223 no pending callbacks, and no open windows,
 224 the runtime unloads the event page and closes the app.
 225 Before unloading the event page,
 226 the <code>onSuspend()</code> event is fired.
 227 This gives the event page opportunity
 228 to do simple clean-up tasks
 229 before the app is closed.
 230 </p>
 231 <h2 id="eventpage">Create event page and windows</h2>
 232 <p>
 233 All apps must have an event page.
 234 This page contains the top-level logic of the application
 235 with none of its own UI and is responsible
 236 for creating the windows for all other app pages.
 237 </p>
 238 <a name="H3-2"></a><h3>Create event page</h3>
 239 <p>
 240 To create the event page,
 241 include the "background" field in the app manifest
 242 and include the <code>background.js</code> in the scripts array.
 243 Any library scripts used by the event page need to be added
 244 to the "background" field first:
 245 </p>
 246 <pre>"background": {
 247   "scripts": [
 248     "foo.js",
 249     "background.js"
 250   ]
 251 }
 252 </pre>
 253 <p>
 254 Your event page must include the <code>onLaunched()</code> function.
 255 This function is called
 256 when your application is launched in any way:
 257 </p>
 258 <pre>chrome.app.runtime.onLaunched.addListener(function() {
 259   // Tell your app what to launch and how.
 260 });
 261 </pre>
 262 <a name="H3-3"></a><h3>Create windows</h3>
 263 <p>
 264 An event page may create one or more windows at its discretion.
 265 By default, these windows are created with a script connection
 266 to the event page and are directly scriptable by the event page.
 267 </p>
 268 <p>
 269 Windows can either be shells or panels.
 270 Shell windows have no browser chrome.
 271 Panel windows are the same as shell windows,
 272 except they have different size and position restrictions,
 273 for example, a chat panel.
 274 </p>
 275 <p>Here's a sample <code>background.js</code>
 276   with a 'shell' window:</p>
 277 <pre>chrome.app.runtime.onLaunched.addListener(function() {
 278   chrome.app.window.create('main.html', {
 279     width: 800,
 280     height: 600,
 281     minWidth: 800,
 282     minHeight: 600,
 283     left: 100,
 284     top: 100,
 285     type: 'shell'
 286   });
 287 });
 288 </pre>
 289 <p>Here's a sample <code>background.js</code>
 290   with a 'panel' window:
 291 </p>
 292 <pre>chrome.app.runtime.onLaunched.addListener(function() {
 293   chrome.app.window.create('index.html', {
 294     width: 400,
 295     height: 200,
 296     type: 'panel'
 297   });
 298 });
 299 </pre>
 300 <a name="H3-4"></a><h3>Including Launch Data</h3>
 301 <p>
 302 Depending on how your app is launched,
 303 you may need to include launch data
 304 in your event page.
 305 By default, there is no launch data
 306 when the app is started by the app launcher.
 307 For apps that provide intents,
 308 you need to include the
 309 <code>launchData.intent</code> parameter.
 310 </p>
 311 <p>
 312 Web intents can be launched by other apps invoking their intent,
 313 or by the runtime when apps are launched to view or edit files,
 314 for example from the operating system file explorer.
 315 To find out how to launch an app with web intents,
 316 see <a href="app_intents.html#launching">Launching an App with a File</a>.
 317 </p>
 318 <h2 id="runtime">Listening for app runtime events</h2>
 319 <p>
 320 The app runtime controls the app installs, updates, and uninstalls.
 321 You don't need to do anything to set up the app runtime,
 322 but your event page can listen out for the <code>onInstalled()</code> event
 323 to store local settings and the
 324 <code>onSuspend()</code> event to do simple clean-up tasks
 325 before the event page is unloaded.
 326 </p>
 327 <a name="H3-6"></a><h3>Storing local settings</h3>
 328 <p>
 329 <code>chrome.runtime.onInstalled()</code>
 330 is called when your app has first been installed,
 331 or when it has been updated.
 332 Any time this function is called,
 333 the <code>onInstalled</code> event is fired.
 334 The event page can listen for this event and use the
 335 <a href="storage.html">Storage API</a>
 336 to store and update local settings
 337 (see also <a href="app_storage.html#options">Storage options</a>).
 338 </p>
 339 <pre>chrome.runtime.onInstalled.addListener(function() {
 340   chrome.storage.local.set(object items, function callback);
 341 });
 342 </pre>
 343 <a name="H3-7"></a><h3>Preventing data loss</h3>
 344 <p>
 345 Users can uninstall your app at any time.
 346 When uninstalled,
 347 no executing code or private data is left behind.
 348 This can lead to data loss
 349 since the users may be uninstalling an app
 350 that has locally edited, unsynchronized data.
 351 You should stash data to prevent data loss.
 352 </p>
 353 <p>
 354 At a minimum,
 355 you should store user settings
 356 so that if users reinstall your app,
 357 their information is still available for reuse.
 358 Using the Storage API
 359 (<a href="storage.html#property-sync">chrome.storage.sync</a>),
 360 user data can be automatically synced
 361 with Chrome sync.
 362 </p>
 363 <a name="H3-8"></a><h3>Clean-up before app closes</h3>
 364 <p>
 365 The app runtime sends the <code>onSuspend()</code>
 366 event to the event page before unloading it.
 367 Your event page can listen out for this event and
 368 do clean-up tasks before the app closes.
 369 </p>
 370 <p>
 371 Once this event is fired,
 372 the app runtime starts the process of closing the app:
 373 all events stop firing and
 374 JavaScript execution is halted.
 375 Any asynchronous operations started
 376 while handling this event are not guaranteed to complete.
 377 Keep the clean-up tasks synchronous and simple.
 378 </p>
 379 <pre>chrome.runtime.onSuspend.addListener(function() {
 380   // Do some simple clean-up tasks.
 381 });
 382 </pre>
 383 <p class="backtotop"><a href="#top">Back to top</a></p>
 384 </div>
 385         <!-- API PAGE -->
 386          <!-- /apiPage -->
 387       </div> <!-- /gc-pagecontent -->
 388     </div> <!-- /g-section -->
 389   </div> <!-- /codesiteContent -->
 390     <div id="gc-footer" --="">
 391       <div class="text">
 392   <p>
 393   Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 394   the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
 395   Attribution 3.0 License</a>, and code samples are licensed under the
 396   <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.
 397   </p>
 398   <p>
 399   ©2012 Google
 400   </p>
 401 <!-- begin analytics -->
 402 <script src="https://www.google-analytics.com/urchin.js" type="text/javascript"></script>
 403 <script src="https://www.google-analytics.com/ga.js" type="text/javascript"></script>
 404 <script src="../js/prettify.js" type="text/javascript"></script>
 405 <script>
 406   // Auto syntax highlight all pre tags.
 407   var pres = document.querySelectorAll('pre');
 408   for (var i = 0, pre; pre = pres[i]; ++i) {
 409     pre.className += ' prettyprint';
 410   };
 411   prettyPrint();
 412 </script>
 413 <script type="text/javascript">
 414   // chrome doc tracking
 415   try {
 416     var engdocs = _gat._getTracker("YT-10763712-2");
 417     engdocs._trackPageview();
 418   } catch(err) {}
 419   // code.google.com site-wide tracking
 420   try {
 421     _uacct="UA-18071-1";
 422     _uanchor=1;
 423     _uff=0;
 424     urchinTracker();
 425   }
 426   catch(e) {/* urchinTracker not available. */}
 427 </script>
 428 <!-- end analytics -->
 429       </div>
 430     </div> <!-- /gc-footer -->
 431   </div> <!-- /gc-container -->
 432 </body></html>