1 {{+bindTo:partials.standard_nacl_article}} 2 3 <section id="distributing-your-application"> 4 <span id="distributing"></span><h1 id="distributing-your-application"><span id="distributing"></span>Distributing Your Application</h1> 5 <div class="contents local" id="contents" style="display: none"> 6 <ul class="small-gap"> 7 <li><a class="reference internal" href="#portable-native-client" id="id1">Portable Native Client</a></li> 8 <li><p class="first"><a class="reference internal" href="#non-portable-native-client" id="id2">Non-portable Native Client</a></p> 9 <ul class="small-gap"> 10 <li><a class="reference internal" href="#packaged-application" id="id3">Packaged application</a></li> 11 <li><a class="reference internal" href="#extension" id="id4">Extension</a></li> 12 <li><a class="reference internal" href="#hosted-application" id="id5">Hosted application</a></li> 13 <li><a class="reference internal" href="#registering-native-client-modules-to-handle-mime-types" id="id6">Registering Native Client modules to handle MIME types</a></li> 14 </ul> 15 </li> 16 </ul> 17 18 </div><p>This document describes how to distribute Portable Native Client applications 19 on the web, and Native Client applications through the 20 <a class="reference external" href="/webstore">Chrome Web Store</a> (CWS).</p> 21 <section id="portable-native-client"> 22 <h2 id="portable-native-client">Portable Native Client</h2> 23 <p>Portable Native Client is enabled by default for web pages, so no separate 24 distribution step is requred. Making PNaCl a part of your web application is as 25 simple as embedding a manifest file that points to a <strong>pexe</strong>. See the 26 <a class="reference internal" href="/native-client/overview.html"><em>technical overview</em></a> for more details.</p> 27 <img alt="/native-client/images/nacl-in-a-web-app.png" src="/native-client/images/nacl-in-a-web-app.png" /> 28 <p>The only constraint for distributing PNaCl modules with a web application is 29 abiding by the <a class="reference external" href="http://en.wikipedia.org/wiki/Same_origin_policy">Same-origin policy</a>. The PNaCl manifest and 30 <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 31 mechanism</a> should 32 be used to safely host them on a different domain.</p> 33 </section><section id="non-portable-native-client"> 34 <h2 id="non-portable-native-client">Non-portable Native Client</h2> 35 <p>NaCl modules are only allowed for applications distributed through the <a class="reference external" href="https://chrome.google.com/webstore/category/apps">Chrome 36 Web Store (CWS)</a> 37 The CWS requirement is in place to prevent the proliferation of Native Client 38 executables (<strong>nexe</strong>s) compiled for specific architecures (e.g., x86-32, 39 x86-64, or ARM).</p> 40 <p>In general, the considerations and guidelines for distributing applications 41 through the Chrome Web Store apply to applications that contain NaCl modules as 42 well. Here are a few pointers to relevant documentation:</p> 43 <ul class="small-gap"> 44 <li><a class="reference external" href="/webstore">CWS Overview</a></li> 45 <li><a class="reference external" href="/webstore/choosing">Choosing an App Type</a></li> 46 <li><a class="reference external" href="/apps/about_apps">Getting started with packaged apps</a></li> 47 <li><a class="reference external" href="https://developers.google.com/chrome/apps/docs/developers_guide">Hosted apps</a></li> 48 <li><a class="reference external" href="/extensions">Chrome extensions</a></li> 49 </ul> 50 <p>In this document, we’ll focus only on distribution issues specific to 51 applications that contain NaCl modules.</p> 52 <section id="packaged-application"> 53 <span id="distributing-packaged"></span><h3 id="packaged-application"><span id="distributing-packaged"></span>Packaged application</h3> 54 <p>A packaged application is a special zip file (with a .crx extension) hosted in 55 the Chrome Web Store. This file contains all of the application parts: A Chrome 56 Web Store manifest file (manifest.json), an icon, and all of the regular Native 57 Client application files. Refer to 58 <a class="reference external" href="/apps/about_apps">Packaged Apps</a> 59 for more information about creating a packaged application.</p> 60 <section id="reducing-the-size-of-the-user-download-package"> 61 <h4 id="reducing-the-size-of-the-user-download-package">Reducing the size of the user download package</h4> 62 <aside class="note"> 63 <strong>Tip:</strong> 64 Packaging an app in a multi-platform zip file can significantly reduce the 65 download and storage requirements for the app. 66 </aside> 67 <p>As described above, to upload a packaged app to the CWS you have to create a zip 68 file with all the resources that your app needs, including .nexe files for 69 multiple architectures (x86-64, x86-32, and ARM). Prior to Chrome 28, when users 70 installed your app they had to download a .crx file from the CWS with all the 71 included .nexe files.</p> 72 <p>Starting with Chrome 28, the Chrome Web Store includes a feature called 73 <strong>multi-platform zip files.</strong> This feature lets you structure your application 74 directory and zip file in a way that reduces the size of the user download 75 package. Here’s how this feature works:</p> 76 <ul class="small-gap"> 77 <li>You still include all the .nexe files in the zip file that you upload to 78 the CWS, but you designate specific .nexe files (and other files if 79 appropriate) for specific architectures.</li> 80 <li>The Chrome Web Store re-packages your app, so that users only download 81 the files that they need for their specific architecture.</li> 82 </ul> 83 <p>Here is how to use this feature:</p> 84 <ol class="arabic"> 85 <li><p class="first">Create a directory called <code>_platform_specific</code>. 86 Put this directory at the same level where your CWS manifest file, 87 <code>manifest.json</code>, is located.</p> 88 </li> 89 <li><p class="first">Create a subdirectory for each specific architecture that you support, 90 and add the files for each architecture in the relevant subdirectory.</p> 91 <p>Here is a sample app directory structure:</p> 92 <pre> 93 |-- my_app_directory/ 94 | |-- manifest.json 95 | |-- my_app.html 96 | |-- my_module.nmf 97 | +-- css/ 98 | +-- images/ 99 | +-- scripts/ 100 | |-- _platform_specific/ 101 | | |-- x86-64/ 102 | | | |-- my_module_x86_64.nexe 103 | | |-- x86-32/ 104 | | | |-- my_module_x86_32.nexe 105 | | |-- arm/ 106 | | | |-- my_module_arm.nexe 107 | | |-- all/ 108 | | | |-- my_module_x86_64.nexe 109 | | | |-- my_module_x86_64.nexe 110 | | | |-- my_module_x86_32.nexe 111 </pre> 112 <p>Please note a few important points about the app directory structure:</p> 113 <ul class="small-gap"> 114 <li><p class="first">The architecture-specific subdirectories:</p> 115 <ul class="small-gap"> 116 <li><p class="first">can have arbitrary names;</p> 117 </li> 118 <li><p class="first">must be directly under the <code>_platform_specific</code> directory; and</p> 119 </li> 120 <li><p class="first">must be listed in the CWS manifest file (see step 3 below).</p> 121 </li> 122 </ul> 123 </li> 124 <li><p class="first">You can include a fallback subdirectory that provides a download package 125 with all the architecture-specific files. (In the example above this 126 is the <code>all/</code> subdirectory.) This folder is used if the user has an 127 earlier version of Chrome (prior to Chrome 28) that does not support 128 multi-platform zip files.</p> 129 </li> 130 <li><p class="first">You cannot include any files directly in the folder 131 <code>_platform_specific</code>. All architecture-specific files 132 must be under one of the architecture-specific subdirectories.</p> 133 </li> 134 <li><p class="first">Files that are not under the <code>_platform_specific</code> directory are 135 included in all download packages. (In the example above, that 136 includes <code>my_app.html</code>, <code>my_module.nmf</code>, 137 and the <code>css/</code>, <code>images/</code>, and <code>scripts/</code> directories.)</p> 138 </li> 139 </ul> 140 </li> 141 <li><p class="first">Modify the CWS manifest file, <code>manifest.json</code>, so that it specifies which 142 subdirectory under <code>_platform_specific</code> corresponds to which architecture.</p> 143 <p>The CWS manifest file must include a new name/value pair, where the name 144 is <code>platforms</code> and the value is an array. The array has an object for 145 each Native Client architecture with two name/value pairs:</p> 146 <table border="1" class="docutils"> 147 <colgroup> 148 </colgroup> 149 <thead valign="bottom"> 150 <tr class="row-odd"><th class="head"><p class="first last">Name</p> 151 </th> 152 <th class="head"><p class="first last">Value</p> 153 </th> 154 </tr> 155 </thead> 156 <tbody valign="top"> 157 <tr class="row-even"><td><p class="first last"><code>nacl_arch</code></p> 158 </td> 159 <td><p class="first last"><code>x86-64</code>, <code>x86-32</code>, or <code>arm</code></p> 160 </td> 161 </tr> 162 <tr class="row-odd"><td><p class="first last"><code>sub_package_path</code></p> 163 </td> 164 <td><p class="first last">the path of the directory (starting 165 with <code>_platform_specific</code>) that 166 contains the files for the designated 167 NaCl architecture</p> 168 </td> 169 </tr> 170 </tbody> 171 </table> 172 <p>Here is a sample <code>manifest.json</code> file:</p> 173 <pre> 174 { 175 "name": "My Reminder App", 176 "description": "A reminder app that syncs across Chrome browsers.", 177 "manifest_version": 2, 178 "minimum_chrome_version": "28", 179 "offline_enabled": true, 180 "version": "0.3", 181 "permissions": [ 182 {"fileSystem": ["write"]}, 183 "alarms", 184 "storage" 185 ], 186 "app": { 187 "background": { 188 "scripts": ["scripts/background.js"] 189 } 190 }, 191 "icons": { 192 "16": "images/icon-16x16.png", 193 "128": "images/icon-128x128.png" 194 }, 195 "platforms": [ 196 { 197 "nacl_arch": "x86-64", 198 "sub_package_path": "_platform_specific/x86-64/" 199 }, 200 { 201 "nacl_arch": "x86-32", 202 "sub_package_path": "_platform_specific/x86-32/" 203 }, 204 { 205 "nacl_arch": "arm", 206 "sub_package_path": "_platform_specific/arm/" 207 }, 208 { 209 "sub_package_path": "_platform_specific/all/" 210 } 211 ] 212 } 213 </pre> 214 <p>Note the last entry in the CWS manifest file above, which specifies a 215 <code>sub_package_path</code> without a corresponding <code>nacl_arch</code>. This entry 216 identifies the fallback directory, which is included in the download 217 package if the user architecture does not match any of the listed NaCl 218 architectures, or if the user is using an older version of Chrome that 219 does not support multi-platform zip files.</p> 220 </li> 221 <li><p class="first">Modify your application as necessary so that it uses the files for the 222 correct user architecture.</p> 223 <p>To reference architecture-specific files, use the JavaScript API 224 <a class="reference external" href="/extensions/runtime.html#method-getPlatformInfo">chrome.runtime.getPlatformInfo()</a>. 225 As an example, if you have architecture-specific files in the directories 226 <code>x86-64</code>, <code>x86-32</code>, and <code>arm</code>, you can use the following JavaScript 227 code to create a path for the files:</p> 228 <pre class="prettyprint"> 229 function getPath(name) { 230 return '_platform_specific/' + 231 chrome.runtime.getPlatformInfo().nacl_arch + 232 '/' + name; 233 } 234 </pre> 235 </li> 236 <li><p class="first">Test your app, create a zip file, and upload the app to the CWS as before.</p> 237 </li> 238 </ol> 239 </section><section id="additional-considerations-for-a-packaged-application"> 240 <span id="additional-considerations-packaged"></span><h4 id="additional-considerations-for-a-packaged-application"><span id="additional-considerations-packaged"></span>Additional considerations for a packaged application</h4> 241 <ul class="small-gap"> 242 <li>In the description of your application in the CWS, make sure to mention that 243 your application is a Native Client application that only works with the 244 Chrome browser. Also make sure to identify the minimum version of Chrome 245 that your application requires.</li> 246 <li><p class="first">Hosted and packaged applications have a “launch” parameter in the CWS 247 manifest. This parameter is present only in apps (not extensions), and it 248 tells Google Chrome what to show when a user starts an installed app. For 249 example:</p> 250 <pre> 251 "launch": { 252 "web_url": "http://mail.google.com/mail/"; 253 } 254 </pre> 255 </li> 256 <li>If you want to write local data using the Pepper 257 <a class="reference external" href="/native-client/peppercpp/classpp_1_1_file_i_o">FileIO</a> 258 API, you must set the ‘unlimitedStorage’ permission in your Chrome Web 259 Store manifest file, just as you would for a JavaScript application that 260 uses the HTML5 File API.</li> 261 <li>For packaged applications, you can only use in-app purchases.</li> 262 <li>You can place your application in the Google Web Store with access only to 263 certain people for testing. See <a class="reference external" href="/webstore/publish">Publishing to test accounts</a> for more information.</li> 264 </ul> 265 </section></section><section id="extension"> 266 <h3 id="extension">Extension</h3> 267 <p>The NaCl-specific notes for a <a class="reference internal" href="#distributing-packaged"><em>package application</em></a> 268 apply to extensions as well.</p> 269 </section><section id="hosted-application"> 270 <h3 id="hosted-application">Hosted application</h3> 271 <p>The .html file, .nmf file (Native Client manifest file), and .nexe files must 272 be served from the same domain, and the Chrome Web Store manifest file must 273 specify the correct, verified domain. Other files can be served from the same 274 or another domain.</p> 275 <p>In addition, see <a class="reference internal" href="#additional-considerations-packaged"><em>Additional considerations for a packaged application</em></a>.</p> 276 </section><section id="registering-native-client-modules-to-handle-mime-types"> 277 <h3 id="registering-native-client-modules-to-handle-mime-types">Registering Native Client modules to handle MIME types</h3> 278 <p>If you want Chrome to use a Native Client module to display a particular type 279 of content, you can associate the MIME type of that content with the Native 280 Client module. Use the <code>nacl_modules</code> attribute in the Chrome Web Store 281 manifest file to register a Native Client module as the handler for one or more 282 specific MIME types. For example, the bold code in the snippet below registers 283 a Native Client module as the content handler for the OpenOffice spreadsheet 284 MIME type:</p> 285 <pre> 286 { 287 "name": "My Native Client Spreadsheet Viewer", 288 "version": "0.1", 289 "description": "Open spreadsheets right in your browser.", 290 "nacl_modules": [{ 291 "path": "SpreadsheetViewer.nmf", 292 "mime_type": "application/vnd.oasis.opendocument.spreadsheet" 293 }] 294 } 295 </pre> 296 <p>The value of “path” is the location of a Native Client manifest file (.nmf) 297 within the application directory. For more information on Native Client 298 manifest files, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>Manifest Files</em></a>.</p> 299 <p>The value of “mime_type” is a specific MIME type that you want the Native 300 Client module to handle. Each MIME type can be associated with only one .nmf 301 file, but a single .nmf file might handle multiple MIME types. The following 302 example shows an extension with two .nmf files that handle three MIME types.</p> 303 <pre> 304 { 305 "name": "My Native Client Spreadsheet and Document Viewer", 306 "version": "0.1", 307 "description": "Open spreadsheets and documents right in your browser.", 308 "nacl_modules": [{ 309 "path": "SpreadsheetViewer.nmf", 310 "mime_type": "application/vnd.oasis.opendocument.spreadsheet" 311 }, 312 { 313 "path": "SpreadsheetViewer.nmf", 314 "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template" 315 }, 316 { 317 "path": "DocumentViewer.nmf", 318 "mime_type": "application/vnd.oasis.opendocument.text" 319 }] 320 } 321 </pre> 322 <p>The <code>nacl_modules</code> attribute is optional—specify this attribute only if 323 you want Chrome to use a Native Client module to display a particular type of 324 content.</p> 325 </section></section></section> 326 327 {{/partials.standard_nacl_article}} 328
