native_client_sdk/src/doc/devguide/distributing.rst

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