hosted_apps.html

{{+bindTo:partials.standard_store_article}}
<p class="caution">
  <b>Important:</b>
  Chrome will be removing support for Chrome Apps on Windows, Mac, and
  Linux.  Chrome OS will continue to support Chrome Apps.  Additionally,
  Chrome and the Web Store will continue to support extensions on all
  platforms.
  <a href="http://blog.chromium.org/2016/08/from-chrome-apps-to-web.html">
  Read the announcement</a> and learn more about
  <a href="https://developers.chrome.com/apps/migration">
  migrating your app</a>.
</p>

<h1>Hosted Apps</h1>

<p>
Read this page to learn how to create and load
a <strong>hosted app</strong>&mdash;a
regular web app, plus some metadata.
</p>

<p>
If you're interested in creating a <strong>packaged app</strong>&mdash;a
web app that's bundled up as an extension,
so that the user downloads all of its content&mdash;see
<a href="/extensions/apps">Packaged Apps</a>
in the <a href="/extensions">extensions documentation</a>.
</p>

<h2 id="creating">Creating hosted apps</h2>

<p>
A hosted app requires a <em><code>.crx</code> file</em>
that contains metadata describing the app.
(The <code>.crx</code> file format
is just a variation of ZIP
that's used by Google Chrome.)

An app's <code>.crx</code> file can be hosted on your own server
or, more typically,
by the Chrome Web Store.
</p>

<p>
The <code>.crx</code> file for a hosted app
must contain an icon
and a manifest that has details about how the app should function.
</p>

<p class="note">
<b>Note:</b>
Unlike extensions and packaged apps,
a hosted app has no access to the files inside its <code>.crx</code> file.
</p>

<h3 id="live">Making a web app installable</h3>

<p>
You can easily make any existing web app installable,
letting you publish it as a hosted app.
There's no need to rewrite the web app or change technologies.
All you need to provide are an icon and a manifest.
</p>

<p>
Here is a typical manifest for a hosted app:
</p>

<pre>
{
  "name": "Google Mail",
  "description": "Read your gmail",
  "version": "1",
  "app": {
    "urls": [
      "*://mail.google.com/mail/",
      "*://www.google.com/mail/"
    ],
    "launch": {
      "web_url": "http://mail.google.com/mail/"
    }
  },
  "icons": {
    "128": "icon_128.png"
  },
  "permissions": [
    "unlimitedStorage",
    "notifications"
  ]
}
</pre>


<p>
This manifest and the icon it points to
(<code>icon_128.png</code>)
make the Google Mail web app
installable as a hosted app.
When someone installs this app,
the specified icon appears on Chrome's New Tab page.
Clicking that icon launches the app
by bringing up the page specified by the "web_url" field.
</p>

<p>
The "permissions" field lets you specify
HTML5 permissions that the app requires.
By specifying "unlimitedStorage" and "notifications",
this app is able to use those HTML5 features
without having to repeatedly ask the user for permission.
During app installation,
the user is told which permissions the app needs;
installing the app implicitly grants those permissions for all pages
whose URLs match those in the "apps" field of the manifest.
</p>

<!--Need to test that background content is still accurate-->

<!--<h3 id="background">Keeping a web app alive </h3>

<p>
As of Chrome 10,
you can use the background feature
to specify that your app should always run,
even when the browser and app have no visible windows.
For details, see
<a href="/extensions/background_pages">Background: Extending Your App's Life</a>.
</p>-->


<h3 id="manifest">Details: The manifest</h3>

<p>
The manifest is a file named <code>manifest.json</code>
that can have the following fields:
</p>

<dl>
<dt>name:</dt>
  <dd><em>Required.</em>
  The name of the application.
  This is displayed in the store and in Chrome's launcher.
  </dd>
<dt>description:</dt>
  <dd><em>Recommended.</em>
  A brief description of the app.
  </dd>
<dt>version:</dt>
  <dd><em>Required.</em>
  The version of this metadata.
  Each time you update the metadata this number must be incremented.
  Up to four dot-separated integers are allowed.
  </dd>
<dt>app:</dt>
  <dd><em>Required.</em>
  The URLs that the app uses,
  including the <em>launch page</em> for the app&mdash;the
  page that the browser goes to when the user clicks the app's icon
  in the New Tab page.
  If your hosted app is listed in the Chrome Web Store,
  you must prove that you control
  each domain specified in this field.
  For help in proving your ownership,
  see the <a href="https://chrome.google.com/extensions/developer/dashboard">Chrome Developer Dashboard</a>.
    </p>

  <dl>
  <dt>urls:</dt>
    <dd>
    The URLs for the pages in the hosted app,
    not necessarily including the launch page.
    Once the app is installed,
    these pages and the launch page have the permissions
    requested in the manifest.

    <p class="note">
    <b>Note:</b>
    You don't need to specify the URLs for included files
    or for assets such as images.
    </p>

    <p>
    Each URL must begin with
    <code>http</code>, <code>https</code>, or <code>*</code>
    (which matches both
    <code>http</code> and <code>https</code>).
    You can use wildcards for subdomains&mdash;for example,
    "*://*.example.com/".
    </p>

    <p class="caution">
    <b>Important:</b>
    <em>Do not</em> put port numbers in the value of "urls".
    Port numbers aren't necessary there (all ports are valid),
    and values with port numbers are silently ignored,
    leaving the corresponding pages
    without the requested permissions.

    </p>

    <p>
    You need to specify only the start of the app's URLs.
    For example, "https://www.google.com/accounts/"
    matches every URL that starts with that string,
    such as https://www.google.com/accounts/
    and https://www.google.com/accounts/b/0/ManageAccount.
    </p>

    <p class="caution">
    <b>Important:</b>
    If you provide multiple apps,
    <b>avoid overlapping URLs</b>.
    If a user tries to install an app
    whose "web_url" or "urls" values overlap
    with those of an already installed app,
    the second installation will fail
    due to URL conflict errors.
    For example, an app that specifies a "urls" value of
    "http://mail.example.com/"
    would conflict with an app that specifies
    "http://mail.example.com/mail/".
    </p>

    <p>
    If the user downloads the app's <code>.crx</code> file
    from a server that's not the Chrome Web Store,
    only one domain is allowed,
    and it must be the same as the domain
    that serves the <code>.crx</code> file.
    For more information on hosting options,
    see the extensions documentation for
    <a href="/extensions/hosting">Hosting</a>.
    </p>
    </dd>

  <dt>launch:</dt>
    <dd><em>Required.</em>
    Specifies what happens when the user launches the app.

    <dl>
      <dt>web_url:</dt>
        <dd><em>Required.</em>
        Specifies the launch page
        as an absolute URL.
        </dd>
      <dt>container:</dt>
        <dd> The value "panel" makes the app appear
        in an app panel.
        By default, or when you specify "tab",
        the app appears in a tab.


        </dd>
      <dt>height:</dt>
        <dd>
        If the container is set to "panel",
        this integer specifies the height
        of the panel in pixels.
        For example, you might specify
        <code>"height":400</code>.
        Note that you don't use quotation marks in the value.
        This field specifies the height of the area
        to display contents in;
        window decorations add a few more pixels to the total height.
        If the container isn't a panel, this field is ignored.
        </dd>
      <dt>width:</dt>
        <dd>
        Similar to "height",
        but specifies the width of the panel.
        </dd>
      </dd>
    </dl>
  </dd>
  </dl>

<dt>background_page:</dt>
  <dd>
  Specifies an HTTPS URL to load in a background window.
  If you use this, you must also specify the "background" permission.
  </dd>
</dt>

<dt>icons:</dt>
  <dd><em>Recommended.</em>
  Specifies the icon shown in the launcher.
    <dl>
      <dt>128:</dt>
        <dd> The 128x128 icon shown in the app launcher.
          Only about a 96x96 area should be visible;
          the rest should be transparent.
          For details, see the Chrome Web Store
          <a href="/webstore/images">image guidelines</a>.
        </dd>
    </dl>
   </dd>

<dt>key:</dt>
  <dd>
  The public key value for your app.
  Usually, you don't need to specify this field;
  it's set automatically when the <code>.crx</code> file is created,
  such as when you upload your app to the Chrome Web Store.
  For more information, see
  <a href="/extensions/packaging">Packaging</a>
  and
  <a href="/extensions/manifest/key">key field details</a>
  in the extensions documentation.
  </dd>

<dt>minimum_chrome_version:</dt>
  <dd>
  The version of Chrome
  that your app requires.
  </dd>

<dt id="offline">offline_enabled:</dt>
  <dd>
  Whether the app is expected to work offline.
  When Chrome detects that it is offline,
  apps with this field set to true are highlighted on the New Tab page.
  For help on enabling offline access for your app, see
  <a href="http://www.html5rocks.com/en/tutorials/#offline">these
  articles</a>.

  <p class="note">
  <b>Version note:</b>
  Before Chrome 15, this flag is valid but ignored.
  </p>
  </dd>

<dt>permissions:</dt>
  <dd>Any combination of
  "<a href="/extensions/declare_permissions#background">background</a>",
  "clipboardRead", "clipboardWrite",
  "geolocation", "notifications",
  and "unlimitedStorage".
  </dd>

<dt>update_url:</dt>
  <dd>
  The URL of the XML file
  used to autoupdate your app.
  Don't specify this field
  unless you host your own autoupdates.
  See
  <a href="/extensions/autoupdate">Autoupdating</a>
  for details.
  </dd>
</dl>

<p>
The format of the app manifest file
is based on the manifest files for Chrome extensions,
and most of the fields are the same.
For more details on manifest files and their fields,
see the
<a href="/extensions/manifest">extension
manifest documentation</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="installing">Loading hosted apps</h2>

<p>
The following instructions tell you how
to load an installable web app that isn't yet
packaged in a <code>.crx</code> file&mdash;a
handy technique while you're working on an app.
</p>

<ol>
  <li>
  <p>
  Create a folder (you might name it <code>maps_app</code>)
  and put the following files into it:
  </p>
    <ul>
      <li> <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/maps_app/manifest.json?content-type=text/plain" target="_blank">manifest.json</a> </li>
      <li> <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/maps_app/128.png" target="_blank">128.png</a> </li>
    </ul>

  <p>
  You've just created the metadata for a hosted app.
  Now you can load the app.
  </p>
  </li>

  <li>
  <p>
  In Chrome, bring up the extensions management page
  by clicking the wrench icon and choosing <b>Tools > Extensions</b>.
  </p>
  </li>

  <li>
  <p>
  If <b>Developer mode</b> has a + by it,
  click the +. <br />
  The + changes to a -,
  and more buttons and information appear.
  </p>
  </li>

  <li>
  <p>
  Click the <b>Load unpacked extension</b> button. <br />
  A file dialog appears.
  </p>
  </li>

  <li>
  <p>
  In the file dialog,
  navigate to the folder where you put the app's files,
  and click <b>OK</b>.
  <br />
  You've now installed the app.
  </span>
  </p>

  <li>
  <p>
  Create a new tab.
  <br />
  The icon for the newly installed app appears in Chrome's launcher
  on the New Tab page.
  </p>
  </li>

  <li>
  <p>
  Click the icon for the app.
  <br />
  You've now launched the app.
  </p>
  </li>
</ol>

<p>
For a full tutorial
on converting your existing web app
into a hosted app (and publishing it), see the Chrome Web Store
<a href="get_started_simple">Getting Started tutorial</a>.
</p>


<h2 id="webstore">Hosted apps and the Chrome Web Store</h2>

<p>
The <a href="http://chrome.google.com/webstore">Chrome Web Store</a>
is an open marketplace for web apps
that enables you to reach millions of users with your apps.
The store is integrated with Chrome,
making it easy for Chrome users
to discover apps and install them directly from the store.
For details, see the developer documentation for the store,
especially the
<a href="index.html">Overview</a> and
<a href="get_started_simple.simple">Getting Started tutorial</a>.
</p>

{{/partials.standard_store_article}}