Native Client

Running Native Client Applications

Introduction

This document describes how to run Native Client applications during development.

Before reading about how to run Native Client applications, it's important to understand a little bit about how Native Client applications are distributed. As explained in Distributing Your Application, Native Client applications must currently be distributed through the Chrome Web Store (CWS). Applications in the CWS are one of three types:

  • A hosted application is an application that you host on a server of your choice. To distribute an application as a hosted application, you upload application metadata to the CWS.
  • A packaged application is an application that is hosted in the CWS and downloaded to the user's machine. To distribute an application as a packaged application, you upload the entire application, including all application assets and metadata, to the CWS.
  • An extension is a packaged application that has a tiny UI component (extensions are typically used to extend the functionality of the Chrome browser). To distribute an application as an extension, you upload the entire application, including all application assets and metadata, to the CWS.

It's clearly not convenient to package and upload files to the Chrome Web Store every time you want to run a new build of your application, but there are four alternative techniques you can use to run the application during development. These techniques are listed in the following table and described in detail below. Each technique has certain requirements (NaCl flag, web server, and/or CWS metadata); these are explained in the Requirements section below.

# Technique Requires NaCl flag Requires web server Requires CWS metadata Description
1 local server required required   Run a local server and simply point your browser to your application on the server.
2 packaged application loaded as an unpacked extension     required Load your packaged application into Chrome as an unpacked extension and run it without a server. An unpacked extension is simply an application whose source and metadata files are located in a plain (unzipped) folder on your development machine. The CWS manifest file (explained below) must specify a local_path field.
3 hosted application loaded as an unpacked extension   required required Load your hosted application into Chrome as an unpacked extension and run it from a server (which can be a local server). The CWS manifest file must specify a web_url field.
4 Chrome Web Store application with trusted testers     required This is the standard technique for distributing a packaged or hosted application in the CWS, but you can limit the application to a few trusted testers. This technique requires a server if your application is a hosted application.

Which of the above techniques you use to run your application during development is largely a matter of personal preference (i.e., would you rather start a local server or create CWS metadata?). As a general rule, once you have an idea of how you plan to distribute your application, you should use the corresponding technique during development (technique # 2 for packaged applications and extensions; technique # 3 for hosted applications). Choosing a distribution option depends on a number of factors such as application size, application start-up time, hosting costs, offline functionality, etc. (see Distributing Your Application for details), but you don't need to make a decision about how to distribute your application at the outset.

The next two sections of this document describe a couple of prerequisites for running applications during development (using the correct version of Chrome and turning off the Chrome cache), and explain the three requirements listed in the table above (NaCl flag, web server, and CWS metadata). The subsequent sections of the document provide instructions for how to use each of the four techniques.

Prerequisites

Browser and Pepper versions

Before you run a new build of your application, make sure that you're using the correct version of Chrome. Each version of Chrome supports a corresponding version of the Pepper API. You (and your users) must use a version of Chrome that is equal to or higher than the version of the Pepper API that your application uses. For example, if you compiled your application using the pepper_20 bundle, your application uses the Pepper 20 API, and you must run the application in Chrome 20 or higher. To check which version of Chrome you're using, type about:chrome or about:version in the Chrome address bar (the latter address shows additional information such as the Chrome command line and profile path).

If your application requires a minimum version of Chrome, you are encouraged to include code in the application to check that the user's browser is compatible with the application. For sample code that checks the user's browser version, refer to the load_progress example in the Native Client SDK.

Chrome Cache

Chrome caches resources aggressively. You should disable Chrome's cache whenever you are developing a Native Client application in order to make sure Chrome loads new versions of your application. To disable the cache:

  1. Open Chrome's developer tools by clicking the wrench icon wrench icon and choosing Tools > Developer tools.
  2. Click the gear icon gear icon in the bottom right corner of the Chrome window.
  3. Under the "General" settings, check the box next to "Disable cache".

Requirements

Native Client flag

Native Client is automatically enabled for applications that are installed from the Chrome Web Store. To enable Native Client for applications that are not installed from the Chrome Web Store, you must explicitly turn on the Native Client flag in Chrome as follows:

  1. Type about:flags in the Chrome address bar.
  2. Scroll down to "Native Client".
  3. If the link below "Native Client" says "Disable", then Native Client is already enabled and you don't need to do anything else.
  4. If the link below "Native Client" says "Enable":
    • Click the "Enable" link.
    • Scroll down to the bottom of the page and click the "Relaunch Now" button. Native Client will not be enabled until you relaunch your browser. All browser windows will restart when you relaunch Chrome.

If you enable the Native Client flag and still can't run applications from outside the Chrome Web Store, you may need to enable the Native Client plugin:

  1. Type about:plugins in the Chrome address bar.
  2. Scroll down to "Native Client".
  3. If the link below "Native Client" says "Enable", click the link to enable the Native Client plugin. You do not need to relaunch Chrome after enabling the Native Client plugin.

Web server

For security reasons, Native Client applications must come from a server (you can't simply drag HTML files into your browser). The Native Client SDK comes with a lightweight Python web server that you can run to serve your application locally. The server is included in the examples directory in the SDK bundles (e.g., pepper_20/examples). Here is how to run the server:

  • Windows:
    cd examples
    httpd.cmd
  • Mac, Linux:
    cd examples
    python httpd.py

By default, the server listens for requests on port 5103. To use a different port, simply specify a different port number, e.g.: python httpd.py 5104.

You can use the server to run any application under the examples directory where you started the server. For example, to run the hello_world_interactive example in the SDK, start the server as described above and point your browser to http://localhost:5103/hello_world_interactive/hello_world.html.

Chrome Web Store metadata

Applications published in the Chrome Web Store must be accompanied by CWS metadata—specifically, a Chrome Web Store manifest file named manifest.json, and at least one icon.

Below is an example of a CWS manifest file for a hosted application:

{
  "name": "My NaCl App",
  "description": "Simple game implemented using Native Client",
  "version": "0.1",
  "icons": {
    "128": "nacl_icon_128.jpg"
  },
  "app": {
    "urls": [
      "http://mysubdomain.example.com/"
    ],
    "launch": {
      "web_url": "http://mysubdomain.example.com/my_app_main_page.html"
    }
  }
}

For a packaged application, you can omit the urls field, and replace the web_url field with a local_path field, as shown below:

{
  "name": "My NaCl App",
  "description": "Simple game implemented using Native Client",
  "version": "0.1",
  "icons": {
    "16": "nacl_icon_16.jpg",
    "128": "nacl_icon_128.jpg"
  },
  "app": {
    "launch": {
      "local_path": "my_app_main_page.html"
    }
  }
}

You must put the manifest.json file in the same directory as your application's main HTML page.

If you don't have icons for your application, you can use the following icons as placeholders: nacl_icon_16.jpg and nacl_icon_128.jpg. Put the icons in the same directory as the CWS manifest file.

For more information about CWS manifest files and application icons, see:

Technique 1: Local server

To run your application from a local server:

  1. Enable the Native Client flag in Chrome.
  2. Start a local web server.
  3. Put your application under the examples directory in the SDK bundle you are using (e.g., in the directory pepper_20/examples/my_app).
  4. Access your application on the local server by typing the location of its HTML file in Chrome, e.g.: http://localhost:5103/my_app/my_app_main_page.html.

Note: You don't have to use a local web server—you can use another server if you already have one running. You must still enable the Native Client flag in order to run your application from your server.

Technique 2: Packaged application loaded as an unpacked extension

For development purposes, Chrome lets you load a packaged application as an unpacked extension. To load and run your packaged application as an unpacked extension:

  1. Create a Chrome Web Store manifest file and one or more icons for your application.
    • Follow the instructions above under Chrome Web Store metadata to create these files.
    • Note that the CWS manifest file should contain the local_path field rather than the web_url field.
  2. Put the CWS manifest file and the application icon(s) in the same directory as your application's main HTML page.
  3. Load the application as an unpacked extension in Chrome:
    1. Bring up the extensions management page in Chrome by clicking the wrench icon wrench icon and choosing Tools > Extensions.
    2. Check the box for Developer mode and then click the Load unpacked extension button: extensions management screenshot
    3. In the file dialog that appears, select your application directory. Unless you get an error dialog, you've now installed your app in Chrome.
  4. Open a new tab in Chrome and click the Apps link at the bottom of the page to show your installed apps: apps link on new tab page
  5. The icon for your newly installed app should appear on the New Tab page. Click the icon to launch the app.

For additional information about how to create CWS metadata and load your application into Chrome (including troubleshooting information), see the Chrome Web Store Tutorial: Getting Started.

Technique 3: Hosted application loaded as an unpacked extension

For development purposes, Chrome lets you load a hosted application as an unpacked extension. To load and run your hosted application as an unpacked extension:

  1. Start a web server to serve your application.
    • You can use the local web server included with the Native Client SDK if you want.
  2. Upload your application (.html, .nmf, .nexe, .css, .js, image files, etc.) to the server.
    • If you're using the local server included with the Native Client SDK, simply put your application under the examples directory in the SDK bundle you are using (e.g., in the directory pepper_20/examples/my_app).
  3. Create a Chrome Web Store manifest file and one or more icons for your application.
    • Follow the instructions above under Chrome Web Store metadata to create these files.
    • In the CWS manifest file, the web_url field should specify the location of your application on your server. If you're using the local server included with the SDK, the web_url field should look something like http://localhost:5103/my_app/my_app_main_page.html.
  4. Put the CWS manifest file and the application icon(s) in the same directory as your application's main HTML page.
  5. Load the application as an unpacked extension in Chrome:
    1. Bring up the extensions management page in Chrome by clicking the wrench icon wrench icon and choosing Tools > Extensions.
    2. Check the box for Developer mode and then click the Load unpacked extension button: extensions management screenshot
    3. In the file dialog that appears, select your application directory. Unless you get an error dialog, you've now installed your app in Chrome.
  6. Open a new tab in Chrome and click the Apps link at the bottom of the page to show your installed apps: apps link on new tab page
  7. The icon for your newly installed app should appear on the New Tab page. Click the icon to launch the app.

For additional information about how to create CWS metadata and load your application into Chrome (including troubleshooting information), see the Chrome Web Store Tutorial: Getting Started.

Technique 4: Chrome Web Store application with trusted testers

When you're ready to test your application more broadly, you can upload the application to the Chrome Web Store and let some trusted testers run it. Here is how to do so:

  1. Create the Chrome Web Store metadata required to publish your application:
    • First, create a Chrome Web Store manifest file and one or more icons for your application, as described above under Chrome Web Store metadata. Note that packaged applications must have at least two icons (a 16x16 icon and a 128x128 icon).
    • You also need to create the following additional assets before you can publish your application:
      • a screenshot (size must be 640x400 or 1280x800)
      • a promotional image called a "small tile" (size must be 440x280)
  2. For a packaged application:
    • Create a zip file with the CWS manifest file, the application icons, and all your application files (.html, .nmf, .nexe, .css, .js, image files, etc.)
  3. For a hosted application:
    • Create a zip file with the CWS manifest file and the application icon(s).
    • Upload the application files (.html, .nmf, .nexe, .css, .js, image files, etc.) to the server on which the application is being hosted.
    • Use Google Webmaster Tools to verify ownership of the web site on which the application runs.
  4. Log in to the Chrome Web Store Developer Dashboard.
    • The first time you log in, click the "Add new item" button to display the Google Chrome Web Store Developer Agreement. Review and accept the agreement and then return to the Developer Dashboard.
  5. Click "Edit your tester accounts" at the bottom of the Developer Dashboard.
  6. Enter a series of email addresses for your testers (separated by commas or whitespace), and click the "Save Changes" button.
  7. Click the "Add new item" button to add your application to the Chrome Web Store.
  8. Click the "Choose file" button and select the zip file you created earlier.
  9. Click the "Upload" button; this uploads your zip file and opens the "Edit item" page.
  10. Edit the following required fields on the "Edit item" page:
    • Upload an application icon.
    • Upload a screenshot.
    • Upload a small tile.
    • Select a category for your application (accounting application, action game, etc.).
    • Select a language for your application.
  11. If you are an owner or manager of a Google Group, you can select that group in the "Trusted testers" field.
    • You may want to create a Google Group specifically for your testers. When you add a group to the "Trusted testers" field, all group members will be able to test the application, in addition to the individuals you added to the "trusted tester accounts" field on the Developer Dashboard.
  12. Click the "Publish to test accounts" button at the bottom of the page and click "OK".
  13. A page comes up that shows your application's listing in the Chrome Web Store. Copy the URL and mail it to your trusted testers.
    • When you publish an application to test accounts, the application's CWS listing is visible only to you and to people who are logged into those accounts. Your application won't appear in search results, so you need to give testers a direct link to your application's CWS listing. Users won't be able to find the application by searching in the CWS.

To publish an application to the world after publishing it to test accounts, you must first unpublish the application. For additional information see Publishing Your App, and in particular Publishing to test accounts.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.