16 This document describes how to run Native Client applications during
19 The workflow for PNaCl applications is straightfoward and will only be discussed
20 briefly. For NaCl applications distributed through the web-store, there is a
21 number of options and these will be discussed more in-depth.
23 Portable Native Client (PNaCl) applications
24 ===========================================
26 Running PNaCl applications from the open web is enabled in Chrome version 31 and
27 above; therefore, no special provisions are required to run and test such
28 applications locally. An application that uses a PNaCl module can be tested
29 similarly to any other web application that only consists of HTML, CSS and
32 To better simulate a production environment, it's recommended to start a local
33 web server to serve the application's files. The NaCl SDK comes with a simple
34 local server built in, and the process of using it to run PNaCl applications is
35 described in :ref:`the tutorial <tutorial_step_2>`.
37 Native Client applications and the Chrome Web Store
38 ===================================================
40 Before reading about how to run Native Client applications, it's important to
41 understand a little bit about how Native Client applications are distributed.
42 As explained in :doc:`Distributing Your Application <../distributing>`, Native
43 Client applications must currently be distributed through the **Chrome Web
44 Store (CWS)**. Applications in the CWS are one of three types:
46 * A **hosted application** is an application that you host on a server of your
47 choice. To distribute an application as a hosted application, you upload
48 application metadata to the CWS.
50 * A **packaged application** is an application that is hosted in the CWS and
51 downloaded to the user's machine. To distribute an application as a packaged
52 application, you upload the entire application, including all application
53 assets and metadata, to the CWS.
55 * An **extension** is a packaged application that has a tiny UI component
56 (extensions are typically used to extend the functionality of the Chrome
57 browser). To distribute an application as an extension, you upload the entire
58 application, including all application assets and metadata, to the CWS.
60 It's clearly not convenient to package and upload files to the Chrome Web Store
61 every time you want to run a new build of your application, but there are four
62 alternative techniques you can use to run the application during development.
63 These techniques are listed in the following table and described in detail
64 below. Each technique has certain requirements (NaCl flag, web server, and/or
65 CWS metadata); these are explained in the :ref:`Requirements <requirements>`
69 +--------------------------------------------------------+----------+----------+
70 | Technique | Requires | Requires |
72 | | Server | Metadata |
73 +========================================================+==========+==========+
74 |**1. Local server** | |CHK| | |
78 | Run a local server and simply point your browser to | | |
79 | your application on the server. | | |
84 | This technique requires the NaCl flag. | | |
85 +---------------------------------------------+----------+----------+----------+
86 |**2. Packaged application loaded as an unpacked | | |CHK| |
91 | Load your packaged application into Chrome as an | | |
92 | unpacked extension and run it without a server. An | | |
93 | unpacked extension is an application whose source and | | |
94 | metadata files are located in an unzipped folder on | | |
95 | your development machine. The CWS manifest file | | |
96 | (explained below) must specify a local_path field. | | |
97 +--------------------------------------------------------+----------+----------+
98 |**3. Hosted application loaded as an unpacked | |CHK| | |CHK| |
103 | Load your hosted application into Chrome as an | | |
104 | unpacked extension and run it from a server (which can| | |
105 | be a local server). The CWS manifest file must specify| | |
106 | a web_url field. | | |
107 +--------------------------------------------------------+----------+----------+
108 |**4. CWS application with untrusted testers** | | |CHK| |
112 | The standard technique for distributing a packaged or | | |
113 | hosted application in the CWS. You can limit the | | |
114 | application to trusted testers. This technique | | |
115 | requires a server if your application is a hosted | | |
117 +--------------------------------------------------------+----------+----------+
120 .. |CHK| image:: /images/check-red.png
122 Which of the above techniques you use to run your application during development
123 is largely a matter of personal preference (i.e., would you rather start a local
124 server or create CWS metadata?). As a general rule, once you have an idea of how
125 you plan to distribute your application, you should use the corresponding
126 technique during development. Choosing a distribution option depends on a number
127 of factors such as application size, application start-up time, hosting costs,
128 offline functionality, etc. (see :doc:`Distributing Your Application
129 <../distributing>` for details), but you don't need to make a decision about how
130 to distribute your application at the outset.
132 The next two sections of this document describe a couple of prerequisites for
133 running applications during development, and explain the three requirements
134 listed in the table above (NaCl flag, web server, and CWS metadata). The
135 subsequent sections of the document provide instructions for how to use each of
141 Browser and Pepper versions
142 ---------------------------
144 Before you run a new build of your application, make sure that you're using the
145 correct version of Chrome. Each version of Chrome supports a corresponding
146 version of the Pepper API. You (and your users) must use a version of Chrome
147 that is equal to or higher than the version of the Pepper API that your
148 application uses. For example, if you compiled your application using the
149 ``pepper_37`` bundle, your application uses the Pepper 37 API, and you must run
150 the application in Chrome 37 or higher. To check which version of Chrome you're
151 using, type ``about:version`` in the Chrome address bar.
158 Chrome caches resources aggressively. You should disable Chrome's cache whenever
159 you are developing a Native Client application in order to make sure Chrome
160 loads new versions of your application. Follow the instructions :ref:`in the
161 tutorial <tutorial_step_3>`.
173 Native Client is automatically enabled for applications that are installed from
174 the Chrome Web Store. To enable Native Client for applications that are not
175 installed from the Chrome Web Store, you must explicitly turn on the Native
176 Client flag in Chrome as follows:
178 #. Type ``about:flags`` in the Chrome address bar.
179 #. Scroll down to "Native Client".
180 #. If the link below "Native Client" says "Disable", then Native Client is
181 already enabled and you don't need to do anything else.
182 #. If the link below "Native Client" says "Enable":
184 * Click the "Enable" link.
185 * Click the "Relaunch Now" button in the bottom of the screen. **Native
186 Client will not be enabled until you relaunch your browser**. All browser
187 windows will restart when you relaunch Chrome.
189 If you enable the Native Client flag and still can't run applications from
190 outside the Chrome Web Store, you may need to enable the Native Client plugin:
192 #. Type ``about:plugins`` in the Chrome address bar.
193 #. Scroll down to "Native Client".
194 #. If the link below "Native Client" says "Enable", click the link to enable
195 the Native Client plugin. You do not need to relaunch Chrome after enabling
196 the Native Client plugin.
203 For security reasons, Native Client applications must come from a server (you
204 can't simply drag HTML files into your browser). The Native Client SDK comes
205 with a lightweight Python web server that you can run to serve your application
206 locally. The server can be invoked from a Makefile. Here is how to run the
215 By default, the server listens for requests on port 5103. You can use the server
216 to run most applications under the ``examples`` directory where you started the
217 server. For example, to run the ``flock`` example in the SDK, start the server
218 and point your browser to ``http://localhost:5103/demo/flock/``.
220 Some of the applications need special flags to Chrome, and must be run with the
221 ``make run`` command. See :ref:`running_the_sdk_examples` for more details.
225 Chrome Web Store metadata
226 ~~~~~~~~~~~~~~~~~~~~~~~~~
228 Applications published in the Chrome Web Store must be accompanied by CWS
229 metadata; specifically, a Chrome Web Store manifest file named
230 ``manifest.json``, and at least one icon.
232 Below is an example of a CWS manifest file for a **hosted application**:
237 "name": "My NaCl App",
238 "description": "Simple game implemented using Native Client",
245 "http://mysubdomain.example.com/"
248 "web_url": "http://mysubdomain.example.com/my_app_main_page.html"
254 For a **packaged application**, you can omit the urls field, and replace the
255 ``web_url`` field with a ``local_path`` field, as shown below:
260 "name": "My NaCl App",
261 "description": "Simple game implemented using Native Client",
269 "local_path": "my_app_main_page.html"
274 You must put the ``manifest.json`` file in the same directory as your
275 application's main HTML page.
277 If you don't have icons for your application, you can use the following icons as
284 .. |ICON16| image:: /images/icon16.png
285 .. |ICON128| image:: /images/icon128.png
287 Put the icons in the same directory as the CWS manifest file. For more
288 information about CWS manifest files and application icons, see:
290 * `Chrome Web Store Tutorial: Getting Started </webstore/get_started_simple>`_
291 * `Chrome Web Store Formats: Manifest Files </extensions/manifest>`_
293 Technique 1: Local server
294 =========================
296 To run your application from a local server:
298 * Enable the :ref:`Native Client flag <flag>` in Chrome.
299 * Start a :ref:`local web server <web_server>`.
300 * Put your application under the examples directory in the SDK bundle you are
301 using (for example, in the directory ``pepper_35/examples/my_app``).
302 * Access your application on the local server by typing the location of its
303 HTML file in Chrome, for example:
304 ``http://localhost:5103/my_app/my_app_main_page.html``.
309 **Note:** You don't have to use a local web server---you can use another
310 server if you already have one running. You must still enable the Native
311 Client flag in order to run your application from the server.
313 Technique 2: Packaged application loaded as an unpacked extension
314 =================================================================
316 For development purposes, Chrome lets you load a packaged application as an
317 unpacked extension. To load and run your packaged application as an unpacked
320 #. Create a Chrome Web Store manifest file and one or more icons for your
323 * Follow the instructions above under Chrome Web Store metadata to create
325 * Note that the CWS manifest file should contain the ``local_path`` field
326 rather than the ``web_url`` field.
327 #. Put the CWS manifest file and the application icon(s) in the same directory
328 as your application's main HTML page.
329 #. Load the application as an unpacked extension in Chrome:
331 * Bring up the extensions management page in Chrome by clicking the menu
332 icon |menu-icon| and choosing **Tools > Extensions**.
333 * Check the box for **Developer mode** and then click the **Load unpacked
336 * In the file dialog that appears, select your application directory. Unless
337 you get an error dialog, you've now installed your app in Chrome.
338 #. Open a new tab in Chrome and click the **Apps** link at the bottom of the
339 page to show your installed apps:
341 #. The icon for your newly installed app should appear on the New Tab page.
342 Click the icon to launch the app.
344 For additional information about how to create CWS metadata and load your
345 application into Chrome (including troubleshooting information), see the
346 `Chrome Web Store Tutorial: Getting Started </webstore/get_started_simple>`_.
348 See also :ref:`run_sdk_examples_as_packaged`.
350 Technique 3: Hosted application loaded as an unpacked extension
351 ===============================================================
353 For development purposes, Chrome lets you load a hosted application as an
354 unpacked extension. To load and run your hosted application as an unpacked
357 #. Start a web server to serve your application.
359 * You can use the :ref:`local web server <web_server>` included with the
360 Native Client SDK if you want.
361 #. Upload your application (.html, .nmf, .nexe, .css, .js, image files, etc.)
364 * If you're using the local server included with the Native Client SDK,
365 simply put your application under the ``examples`` directory in the SDK
366 bundle you are using (e.g., in the directory
367 ``pepper_37/examples/my_app``).
368 #. Create a Chrome Web Store manifest file and one or more icons for your
371 * Follow the instructions above under :ref:`Chrome Web Store metadata
372 <metadata>` to create these files.
373 * In the CWS manifest file, the ``web_url`` field should specify the
374 location of your application on your server. If you're using the local
375 server included with the SDK, the ``web_url`` field should look something
376 like ``http://localhost:5103/my_app/my_app_main_page.html``.
377 #. Put the CWS manifest file and the application icon(s) in the same directory
378 as your application's main HTML page.
379 #. Load the application as an unpacked extension in Chrome:
381 * Bring up the extensions management page in Chrome by clicking the menu
382 icon |menu-icon| and choosing **Tools > Extensions**.
383 * Check the box for **Developer mode** and then click the **Load unpacked
386 * In the file dialog that appears, select your application directory. Unless
387 you get an error dialog, you've now installed your app in Chrome.
388 #. Open a new tab in Chrome and click the **Apps** link at the bottom of the
389 page to show your installed apps:
391 #. The icon for your newly installed app should appear on the New Tab page.
392 Click the icon to launch the app.
394 For additional information about how to create CWS metadata and load your
395 application into Chrome (including troubleshooting information), see the
396 `Chrome Web Store Tutorial: Getting Started </webstore/get_started_simple>`_.
398 Technique 4: Chrome Web Store application with trusted testers
399 ==============================================================
401 When you're ready to test your application more broadly, you can upload the
402 application to the Chrome Web Store and let some trusted testers run it. Here
405 #. Create the Chrome Web Store metadata required to publish your application:
407 * First, create a Chrome Web Store manifest file and one or more icons for
408 your application, as described above under :ref:`Chrome Web Store metadata
409 <metadata>`. Note that packaged applications must have at least two icons
410 (a 16x16 icon and a 128x128 icon).
411 * You also need to create the following additional assets before you can
412 publish your application:
414 * a screenshot (size must be 640x400 or 1280x800)
415 * a promotional image called a "small tile" (size must be 440x280)
417 #. For a **packaged application**:
419 * Create a zip file with the CWS manifest file, the application icons, and
420 all your application files (.html, .nmf, .nexe, .css, .js, image files,
423 #. For a **hosted application**:
425 * Create a zip file with the CWS manifest file and the application icon(s).
426 * Upload the application files (.html, .nmf, .nexe, .css, .js, image files,
427 etc.) to the server on which the application is being hosted.
428 * Use `Google Webmaster Tools <http://www.google.com/webmasters/tools/>`_ to
429 verify ownership of the website on which the application runs.
431 #. Log in to the `Chrome Web Store Developer Dashboard
432 <https://chrome.google.com/webstore/developer/dashboard>`_.
434 * The first time you log in, click the "Add new item" button to display the
435 Google Chrome Web Store Developer Agreement. Review and accept the
436 agreement and then return to the `Developer Dashboard
437 <https://chrome.google.com/webstore/developer/dashboard>`_.
439 #. Click "Edit your tester accounts" at the bottom of the Developer Dashboard.
440 #. Enter a series of email addresses for your testers (separated by commas or
441 whitespace), and click the "Save Changes" button.
442 #. Click the "Add new item" button to add your application to the Chrome Web
444 #. Click the "Choose file" button and select the zip file you created earlier.
445 #. Click the "Upload" button; this uploads your zip file and opens the "Edit
447 #. Edit the following required fields on the "Edit item" page:
449 * Upload an application icon.
450 * Upload a screenshot.
451 * Upload a small tile.
452 * Select a category for your application (accounting application, action
454 * Select a language for your application.
455 #. If you are an owner or manager of a Google Group, you can select that group
456 in the "Trusted testers" field.
458 * You may want to create a Google Group specifically for your testers. When
459 you add a group to the "Trusted testers" field, all group members will be
460 able to test the application, in addition to the individuals you added to
461 the "trusted tester accounts" field on the Developer Dashboard.
462 #. Click the "Publish to test accounts" button at the bottom of the page and
464 #. A page comes up that shows your application's listing in the Chrome Web
465 Store. Copy the URL and mail it to your trusted testers.
467 * When you publish an application to test accounts, the application's CWS
468 listing is visible only to you and to people who are logged into those
469 accounts. Your application won't appear in search results, so you need to
470 give testers a direct link to your application's CWS listing. Users won't
471 be able to find the application by searching in the CWS.
473 To publish an application to the world after publishing it to test accounts,
474 you must first unpublish the application. For additional information see
475 `Publishing Your App </webstore/docs/publish>`_, and in particular `Publishing
476 to test accounts </webstore/publish#testaccounts>`_.
478 .. |menu-icon| image:: /images/menu-icon.png
479 .. |extensions| image:: /images/extensions-management.png
480 .. |new-tab-apps| image:: /images/new-tab-apps.png