| {{+bindTo:partials.standard_nacl_article}} |
| |
| <section id="distributing-your-application"> |
| <span id="distributing"></span><h1 id="distributing-your-application"><span id="distributing"></span>Distributing Your Application</h1> |
| <div class="contents local" id="contents" style="display: none"> |
| <ul class="small-gap"> |
| <li><a class="reference internal" href="#portable-native-client" id="id2">Portable Native Client</a></li> |
| <li><p class="first"><a class="reference internal" href="#non-portable-native-client" id="id3">Non-portable Native Client</a></p> |
| <ul class="small-gap"> |
| <li><a class="reference internal" href="#chrome-apps" id="id4">Chrome apps</a></li> |
| <li><a class="reference internal" href="#extension" id="id5">Extension</a></li> |
| <li><a class="reference internal" href="#hosted-application" id="id6">Hosted application</a></li> |
| <li><a class="reference internal" href="#registering-native-client-modules-to-handle-mime-types" id="id7">Registering Native Client modules to handle MIME types</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| </div><p>This document describes how to distribute Portable Native Client applications |
| on the web, and Native Client applications through the |
| <a class="reference external" href="/webstore">Chrome Web Store</a> (CWS).</p> |
| <h2 id="portable-native-client">Portable Native Client</h2> |
| <p>Portable Native Client is enabled by default for web pages, so no separate |
| distribution step is requred. Making PNaCl a part of your web application is as |
| simple as embedding a manifest file that points to a <strong>pexe</strong>. See the |
| <a class="reference internal" href="/native-client/overview.html"><em>technical overview</em></a> for more details.</p> |
| <img alt="/native-client/images/nacl-in-a-web-app.png" src="/native-client/images/nacl-in-a-web-app.png" /> |
| <p>The only constraint for distributing PNaCl modules with a web application is |
| abiding by the <a class="reference external" href="http://en.wikipedia.org/wiki/Same_origin_policy">Same-origin policy</a>. The PNaCl manifest and |
| <strong>pexe</strong> must either be served from the same domain with the HTML, or the <a class="reference external" href="http://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS |
| mechanism</a> should |
| be used to safely host them on a different domain.</p> |
| <h2 id="non-portable-native-client">Non-portable Native Client</h2> |
| <p>NaCl modules are only allowed for applications distributed through the <a class="reference external" href="https://chrome.google.com/webstore/category/apps">Chrome |
| Web Store (CWS)</a> |
| The CWS requirement is in place to prevent the proliferation of Native Client |
| executables (<strong>nexe</strong>s) compiled for specific architecures (e.g., x86-32, |
| x86-64, or ARM).</p> |
| <p>In general, the considerations and guidelines for distributing applications |
| through the Chrome Web Store apply to applications that contain NaCl modules as |
| well. Here are a few pointers to relevant documentation:</p> |
| <ul class="small-gap"> |
| <li><a class="reference external" href="/webstore">CWS Overview</a></li> |
| <li><a class="reference external" href="/webstore/choosing">Choosing an App Type</a></li> |
| <li><a class="reference external" href="/apps">Getting started with Chrome apps</a></li> |
| <li><a class="reference external" href="/extensions">Chrome extensions</a></li> |
| </ul> |
| <p>In this document, we’ll focus only on distribution issues specific to |
| applications that contain NaCl modules.</p> |
| <h3 id="chrome-apps"><span id="distributing-packaged"></span>Chrome apps</h3> |
| <p>A Chrome app is a special zip file (with a .crx extension) hosted in the Chrome |
| Web Store. This file contains all of the application parts: A Chrome Web Store |
| manifest file (manifest.json), an icon, and all of the regular Native Client |
| application files. Refer to <a class="reference external" href="/apps">Chrome Apps</a> for more information about |
| creating a Chrome app.</p> |
| <h4 id="reducing-the-size-of-the-user-download-package">Reducing the size of the user download package</h4> |
| <aside class="note"> |
| <strong>Tip:</strong> |
| Packaging an app in a multi-platform zip file can significantly reduce the |
| download and storage requirements for the app. |
| </aside> |
| <p>As described above, to upload a Chrome app to the CWS you have to create a zip |
| file with all the resources that your app needs, including .nexe files for |
| multiple architectures (x86-64, x86-32, and ARM). Prior to Chrome 28, when users |
| installed your app they had to download a .crx file from the CWS with all the |
| included .nexe files.</p> |
| <p>Starting with Chrome 28, the Chrome Web Store includes a feature called |
| <strong>multi-platform zip files.</strong> This feature lets you structure your application |
| directory and zip file in a way that reduces the size of the user download |
| package. Here’s how this feature works:</p> |
| <ul class="small-gap"> |
| <li>You still include all the .nexe files in the zip file that you upload to |
| the CWS, but you designate specific .nexe files (and other files if |
| appropriate) for specific architectures.</li> |
| <li>The Chrome Web Store re-packages your app, so that users only download |
| the files that they need for their specific architecture.</li> |
| </ul> |
| <p>Here is how to use this feature:</p> |
| <ol class="arabic"> |
| <li><p class="first">Create a directory called <code>_platform_specific</code>. |
| Put this directory at the same level where your CWS manifest file, |
| <code>manifest.json</code>, is located.</p> |
| </li> |
| <li><p class="first">Create a subdirectory for each specific architecture that you support, |
| and add the files for each architecture in the relevant subdirectory.</p> |
| <p>Here is a sample app directory structure:</p> |
| <pre> |
| |-- my_app_directory/ |
| | |-- manifest.json |
| | |-- my_app.html |
| | |-- my_module.nmf |
| | +-- css/ |
| | +-- images/ |
| | +-- scripts/ |
| | |-- _platform_specific/ |
| | | |-- x86-64/ |
| | | | |-- my_module_x86_64.nexe |
| | | |-- x86-32/ |
| | | | |-- my_module_x86_32.nexe |
| | | |-- arm/ |
| | | | |-- my_module_arm.nexe |
| | | |-- all/ |
| | | | |-- my_module_x86_64.nexe |
| | | | |-- my_module_x86_64.nexe |
| | | | |-- my_module_x86_32.nexe |
| </pre> |
| <p>Please note a few important points about the app directory structure:</p> |
| <ul class="small-gap"> |
| <li><p class="first">The architecture-specific subdirectories:</p> |
| <ul class="small-gap"> |
| <li><p class="first">can have arbitrary names;</p> |
| </li> |
| <li><p class="first">must be directly under the <code>_platform_specific</code> directory; and</p> |
| </li> |
| <li><p class="first">must be listed in the CWS manifest file (see step 3 below).</p> |
| </li> |
| </ul> |
| </li> |
| <li><p class="first">You can include a fallback subdirectory that provides a download package |
| with all the architecture-specific files. (In the example above this |
| is the <code>all/</code> subdirectory.) This folder is used if the user has an |
| earlier version of Chrome (prior to Chrome 28) that does not support |
| multi-platform zip files.</p> |
| </li> |
| <li><p class="first">You cannot include any files directly in the folder |
| <code>_platform_specific</code>. All architecture-specific files |
| must be under one of the architecture-specific subdirectories.</p> |
| </li> |
| <li><p class="first">Files that are not under the <code>_platform_specific</code> directory are |
| included in all download packages. (In the example above, that |
| includes <code>my_app.html</code>, <code>my_module.nmf</code>, |
| and the <code>css/</code>, <code>images/</code>, and <code>scripts/</code> directories.)</p> |
| </li> |
| </ul> |
| </li> |
| <li><p class="first">Modify the CWS manifest file, <code>manifest.json</code>, so that it specifies which |
| subdirectory under <code>_platform_specific</code> corresponds to which architecture.</p> |
| <p>The CWS manifest file must include a new name/value pair, where the name |
| is <code>platforms</code> and the value is an array. The array has an object for |
| each Native Client architecture with two name/value pairs:</p> |
| <table border="1" class="docutils"> |
| <colgroup> |
| </colgroup> |
| <thead valign="bottom"> |
| <tr class="row-odd"><th class="head">Name</th> |
| <th class="head">Value</th> |
| </tr> |
| </thead> |
| <tbody valign="top"> |
| <tr class="row-even"><td><code>nacl_arch</code></td> |
| <td><code>x86-64</code>, <code>x86-32</code>, or <code>arm</code></td> |
| </tr> |
| <tr class="row-odd"><td><code>sub_package_path</code></td> |
| <td>the path of the directory (starting |
| with <code>_platform_specific</code>) that |
| contains the files for the designated |
| NaCl architecture</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>Here is a sample <code>manifest.json</code> file:</p> |
| <pre> |
| { |
| "name": "My Reminder App", |
| "description": "A reminder app that syncs across Chrome browsers.", |
| "manifest_version": 2, |
| "minimum_chrome_version": "28", |
| "offline_enabled": true, |
| "version": "0.3", |
| "permissions": [ |
| {"fileSystem": ["write"]}, |
| "alarms", |
| "storage" |
| ], |
| "app": { |
| "background": { |
| "scripts": ["scripts/background.js"] |
| } |
| }, |
| "icons": { |
| "16": "images/icon-16x16.png", |
| "128": "images/icon-128x128.png" |
| }, |
| "platforms": [ |
| { |
| "nacl_arch": "x86-64", |
| "sub_package_path": "_platform_specific/x86-64/" |
| }, |
| { |
| "nacl_arch": "x86-32", |
| "sub_package_path": "_platform_specific/x86-32/" |
| }, |
| { |
| "nacl_arch": "arm", |
| "sub_package_path": "_platform_specific/arm/" |
| }, |
| { |
| "sub_package_path": "_platform_specific/all/" |
| } |
| ] |
| } |
| </pre> |
| <p>Note the last entry in the CWS manifest file above, which specifies a |
| <code>sub_package_path</code> without a corresponding <code>nacl_arch</code>. This entry |
| identifies the fallback directory, which is included in the download |
| package if the user architecture does not match any of the listed NaCl |
| architectures, or if the user is using an older version of Chrome that |
| does not support multi-platform zip files.</p> |
| </li> |
| <li><p class="first">Modify your application as necessary so that it uses the files for the |
| correct user architecture.</p> |
| <p>To reference architecture-specific files, use the JavaScript API |
| <a class="reference external" href="/extensions/runtime.html#method-getPlatformInfo">chrome.runtime.getPlatformInfo()</a>. |
| As an example, if you have architecture-specific files in the directories |
| <code>x86-64</code>, <code>x86-32</code>, and <code>arm</code>, you can use the following JavaScript |
| code to create a path for the files:</p> |
| <pre class="prettyprint"> |
| function getPath(name) { |
| return '_platform_specific/' + |
| chrome.runtime.getPlatformInfo().nacl_arch + |
| '/' + name; |
| } |
| </pre> |
| </li> |
| <li><p class="first">Test your app, create a zip file, and upload the app to the CWS as before.</p> |
| </li> |
| </ol> |
| <h4 id="additional-considerations-for-a-chrome-app"><span id="additional-considerations-packaged"></span>Additional considerations for a Chrome app</h4> |
| <ul class="small-gap"> |
| <li>In the description of your application in the CWS, make sure to mention that |
| your application is a Native Client application that only works with the |
| Chrome browser. Also make sure to identify the minimum version of Chrome |
| that your application requires.</li> |
| <li><p class="first">Hosted and packaged applications have a “launch” parameter in the CWS |
| manifest. This parameter is present only in apps (not extensions), and it |
| tells Google Chrome what to show when a user starts an installed app. For |
| example:</p> |
| <pre> |
| "launch": { |
| "web_url": "http://mail.google.com/mail/" |
| } |
| </pre> |
| </li> |
| <li>If you want to write local data using the Pepper |
| <a class="reference external" href="/native-client/peppercpp/classpp_1_1_file_i_o">FileIO</a> |
| API, you must set the ‘unlimitedStorage’ permission in your Chrome Web |
| Store manifest file, just as you would for a JavaScript application that |
| uses the HTML5 File API.</li> |
| <li>For Chrome apps, you can only use in-app purchases.</li> |
| <li>You can place your application in the Google Web Store with access only to |
| certain people for testing. See <a class="reference external" href="/webstore/publish">Publishing to test accounts</a> for more information.</li> |
| </ul> |
| <h3 id="extension">Extension</h3> |
| <p>The NaCl-specific notes for a <a class="reference internal" href="#distributing-packaged"><em>package application</em></a> |
| apply to extensions as well.</p> |
| <h3 id="hosted-application">Hosted application</h3> |
| <p>The .html file, .nmf file (Native Client manifest file), and .nexe files must |
| be served from the same domain, and the Chrome Web Store manifest file must |
| specify the correct, verified domain. Other files can be served from the same |
| or another domain.</p> |
| <p>In addition, see <a class="reference internal" href="#additional-considerations-packaged"><em>Additional considerations for a Chrome apps</em></a>.</p> |
| <h3 id="registering-native-client-modules-to-handle-mime-types">Registering Native Client modules to handle MIME types</h3> |
| <p>If you want Chrome to use a Native Client module to display a particular type |
| of content, you can associate the MIME type of that content with the Native |
| Client module. Use the <code>nacl_modules</code> attribute in the Chrome Web Store |
| manifest file to register a Native Client module as the handler for one or more |
| specific MIME types. For example, the bold code in the snippet below registers |
| a Native Client module as the content handler for the OpenOffice spreadsheet |
| MIME type:</p> |
| <pre> |
| { |
| "name": "My Native Client Spreadsheet Viewer", |
| "version": "0.1", |
| "description": "Open spreadsheets right in your browser.", |
| "nacl_modules": [{ |
| "path": "SpreadsheetViewer.nmf", |
| "mime_type": "application/vnd.oasis.opendocument.spreadsheet" |
| }] |
| } |
| </pre> |
| <p>The value of “path” is the location of a Native Client manifest file (.nmf) |
| within the application directory. For more information on Native Client |
| manifest files, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>Manifest Files</em></a>.</p> |
| <p>The value of “mime_type” is a specific MIME type that you want the Native |
| Client module to handle. Each MIME type can be associated with only one .nmf |
| file, but a single .nmf file might handle multiple MIME types. The following |
| example shows an extension with two .nmf files that handle three MIME types.</p> |
| <pre> |
| { |
| "name": "My Native Client Spreadsheet and Document Viewer", |
| "version": "0.1", |
| "description": "Open spreadsheets and documents right in your browser.", |
| "nacl_modules": [{ |
| "path": "SpreadsheetViewer.nmf", |
| "mime_type": "application/vnd.oasis.opendocument.spreadsheet" |
| }, |
| { |
| "path": "SpreadsheetViewer.nmf", |
| "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template" |
| }, |
| { |
| "path": "DocumentViewer.nmf", |
| "mime_type": "application/vnd.oasis.opendocument.text" |
| }] |
| } |
| </pre> |
| <p>The <code>nacl_modules</code> attribute is optional—specify this attribute only if |
| you want Chrome to use a Native Client module to display a particular type of |
| content.</p> |
| </section> |
| |
| {{/partials.standard_nacl_article}} |
