src/chrome/common/extensions/docs/templates/articles/apps.html

   1 <h1>Packaged Apps</h1>
   2
   3
   4 <p class="warning">
   5 <b>Warning: </b>
   6 All content in this doc refers to the legacy version of packaged apps.
   7 Your legacy packaged apps will still work,
   8 but you won't have access to any of the new APIs.
   9 Check out the new version of
  10 <a href="../apps/about_apps.html">Chrome Apps</a>;
  11 otherwise, you're missing out!
  12 </p>
  13
  14 <p>
  15 This page talks about packaged apps&mdash;how
  16 you implement them,
  17 and how they're different from
  18 extensions and ordinary web apps.
  19 </p>
  20
  21 <h2 id="overview">Overview</h2>
  22
  23 <p>
  24 A packaged app is a web app
  25 that's bundled into a <code>.crx</code> file
  26 and can use Chrome extension features.
  27 You build a packaged app just like you build an extension,
  28 except that a packaged app can't include a
  29 <a href="browserAction.html">browser action</a> or
  30 <a href="pageAction.html">page action</a>.
  31 Instead, a packaged app includes at least one HTML file
  32 within its <code>.crx</code> file
  33 that provides the app's user interface.
  34 </p>
  35
  36 <p>
  37 Packaged apps are a type of
  38 <a href="http://code.google.com/chrome/apps/">installable web app</a>&mdash;a
  39 web app that can be installed in Chrome.
  40 The other type of installable web app is a
  41 <a href="http://code.google.com/chrome/apps/docs/developers_guide.html">hosted app</a>,
  42 which is an ordinary web app with a bit of additional metadata.
  43 </p>
  44
  45 <p>
  46 If you're developing a web app for the Chrome Web Store,
  47 you might want to use a packaged app
  48 instead of a hosted app if any of the following are true:
  49 </p>
  50
  51 <ul>
  52   <li>
  53     You don't want to run a service to host your app.
  54   </li>
  55   <li>
  56     You want to build an app that works really well offline.
  57   </li>
  58   <li>
  59     You want tighter integration with Chrome,
  60     using the extension APIs.
  61   </li>
  62 </ul>
  63
  64 <p>
  65 To learn more about
  66 the differences between web apps and websites,
  67 extensions and packaged apps, and packaged apps and hosted apps,
  68 read these:
  69 </p>
  70
  71 <ul>
  72   <li> <a href="http://code.google.com/chrome/webstore/docs/choosing.html">Choosing an App Type</a> </li>
  73   <li> <a href="http://code.google.com/chrome/apps/articles/thinking_in_web_apps.html">Thinking in Web Apps</a> </li>
  74   <li> <a href="http://code.google.com/chrome/webstore/articles/apps_vs_extensions.html">Extensions, Packaged Apps, and Hosted Apps in the Chrome Web Store</a> </li>
  75 </ul>
  76
  77
  78 <h2 id="manifest"> The manifest </h2>
  79
  80 <p>
  81 A packaged app's manifest can have any field
  82 that's available to extensions,
  83 except for "browser_action" and "page_action".
  84 In addition, a packaged app's manifest <b>must</b>
  85 have an "app" field.
  86 Here is a typical manifest for a packaged app:
  87 </p>
  88
  89 <pre data-filename="manifest.json">
  90 {
  91   "name": "My Awesome Racing Game",
  92   "description": "Enter a world where a Vanagon can beat a Maserati",
  93   "version": "1",
  94   <b>"app": {
  95     "launch": {
  96       "local_path": "main.html"
  97     }
  98   },</b>
  99   "icons": {
 100     "16": "icon_16.png",
 101     "128": "icon_128.png"
 102   }
 103 }
 104 </pre>
 105
 106 <p>
 107 The "app" field has one subfield, "launch",
 108 which specifies the <em>launch page</em> for the app&mdash;the
 109 page (HTML file bundled into the <code>.crx</code> file)
 110 that the browser goes to when the user clicks the app's icon
 111 in the New Tab page.
 112 The "launch" field can contain the following:
 113 </p>
 114
 115 <dl>
 116   <dt>local_path:</dt>
 117     <dd><em>Required.</em>
 118     Specifies the launch page
 119     as a relative path referring to a file
 120     in the <code>.crx</code> package.
 121     </dd>
 122   <dt>container:</dt>
 123     <dd> The value "panel" makes the app appear
 124     in an app panel.
 125     By default, or when you specify "tab",
 126     the app appears in a tab.
 127
 128     <!-- PENDING: In the overview
 129     (or somewhere else before here)
 130     we should show and define both app panels and tabs.
 131     We should link to that place from here. -->
 132     </dd>
 133   <dt>height:</dt>
 134     <dd>
 135     If the container is set to "panel",
 136     this integer specifies the height
 137     of the panel in pixels.
 138     For example, you might specify
 139     <code>"height":400</code>.
 140     Note that you don't use quotation marks in the value.
 141     This field specifies the height of the area
 142     to display contents in;
 143     window decorations add a few more pixels to the total height.
 144     If the container isn't a panel, this field is ignored.
 145     </dd>
 146   <dt>width:</dt>
 147     <dd>
 148     Similar to "height",
 149     but specifies the width of the panel.
 150     </dd>
 151   </dd>
 152 </dl>
 153
 154 <p>
 155 Packaged apps usually provide a 16x16 icon
 156 to be used as the favicon for
 157 tabs that contain app's pages.
 158 They also should provide a 128x128 icon,
 159 but not a 48x48 icon.
 160 See the manifest documentation for the
 161 <a href="manifest/icons.html">"icons" field</a>
 162 for more information.
 163 </p>
 164
 165 <p>
 166 For further details on what a packaged app's manifest can contain, see the
 167 <a href="manifest.html">manifest documentation</a>.
 168 </p>
 169
 170 <h2 id="next">What next?</h2>
 171
 172 <p>
 173 Read the <a href="overview.html">Overview</a> to learn
 174 basic concepts about extensions.
 175 </p>
 176
 177 <p class="backtotop"><a href="#top">Back to top</a></p>