Read this page to learn how to create and load a hosted app—a regular web app, plus some metadata.

If you're interested in creating a packaged app—a web app that's bundled up as an extension, so that the user downloads all of its content—see Packaged Apps in the extensions documentation.

Contents

1. Creating hosted apps
   1. Making a web app installable
   2. Keeping a web app alive
   3. Details: The manifest
2. Loading hosted apps
3. Hosted apps and the Chrome Web Store

Creating hosted apps

A hosted app requires a .crx file that contains metadata describing the app. (The .crx file format is just a variation of ZIP that's used by Google Chrome.) An app's .crx file can be hosted on your own server or, more typically, by the Chrome Web Store.

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

Note: Unlike extensions and packaged apps, a hosted app has no access to the files inside its .crx file.

Making a web app installable

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.

Here is a typical manifest for a hosted app:

{
  "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"
  ]
}

This manifest and the icon it points to (icon_128.png) 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.

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.

Back to top

Keeping a web app alive

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 Background: Extending Your App's Life.

Details: The manifest

The manifest is a file named manifest.json that can have the following fields:

name:

Required. The name of the application. This is displayed in the store and in Chrome's launcher.

description:

Recommended. A brief description of the app.

version:

Required. The version of this metadata. Each time you update the metadata this number must be incremented. Up to four dot-separated integers are allowed.

app:

Required. The URLs that the app uses, including the launch page for the app—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 Chrome Developer Dashboard.

urls:

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.

Note: You don't need to specify the URLs for included files or for assets such as images.

Each URL must begin with http, https, or * (which matches both http and https). You can use wildcards for subdomains—for example, "*://*.example.com/".

Important: Do not 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.

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.

Important: If you provide multiple apps, avoid overlapping URLs. 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/".

If the user downloads the app's .crx 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 .crx file. For more information on hosting options, see the extensions documentation for Hosting.

launch:

Required. Specifies what happens when the user launches the app.

web_url:

Required. Specifies the launch page as an absolute URL.

container:

The value "panel" makes the app appear in an app panel. By default, or when you specify "tab", the app appears in a tab.

height:

If the container is set to "panel", this integer specifies the height of the panel in pixels. For example, you might specify "height":400. 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.

width:

Similar to "height", but specifies the width of the panel.

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 extension manifest documentation.

Back to top

Loading hosted apps

The following instructions tell you how to load an installable web app that isn't yet packaged in a .crx file—a handy technique while you're working on an app.

1. Create a folder (you might name it maps_app) and put the following files into it:

   • manifest.json
   • 128.png

   You've just created the metadata for a hosted app. Now you can load the app.

2. In Chrome, bring up the extensions management page by clicking the wrench icon and choosing Tools > Extensions.

3. If Developer mode has a + by it, click the +.
   The + changes to a -, and more buttons and information appear.

4. Click the Load unpacked extension button.
   A file dialog appears.

5. In the file dialog, navigate to the folder where you put the app's files, and click OK.
   You've now installed the app.

6. Create a new tab.
   The icon for the newly installed app appears in Chrome's launcher on the New Tab page.

7. Click the icon for the app.
   You've now launched the app.

For a full tutorial on converting your existing web app into a hosted app (and publishing it), see the Chrome Web Store Getting Started tutorial.

Hosted apps and the Chrome Web Store

The Chrome Web Store 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 Overview and Getting Started tutorial.

Back to top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.