You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2013/12/07 01:17:21 UTC
[05/12] Version 3.3.0
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/appdev/privacy/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/appdev/privacy/index.md b/docs/en/3.3.0/guide/appdev/privacy/index.md
new file mode 100644
index 0000000..601ee38
--- /dev/null
+++ b/docs/en/3.3.0/guide/appdev/privacy/index.md
@@ -0,0 +1,117 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Privacy Guide
+
+Mobile privacy is a critical issue that every app developer must
+address. Your users expect that their private information will be
+collected and treated appropriately by your app. Also, there are an
+increasing number of jurisdictions that now have legal requirements
+regarding mobile privacy practices.
+
+This guide on mobile app privacy should be considered a _primer_
+addressing some the most significant issues. It outlines some broadly
+accepted best practices and provides references to other more detailed
+guides and references.
+
+* __Privacy Policy__: You app should include a privacy policy that
+ addresses topics such as what kind of information your app collects
+ from or about your users, how that information is used, with whom it
+ is shared, and how users can make privacy-related choices within the
+ app. To aid understanding, you should use plain language and avoid
+ technical jargon. You should make your privacy policy available for
+ users to review prior to download, such as in the app description in
+ the app marketplace. In addition, you should make your privacy
+ policy available within the app itself. The limited size of mobile
+ device displays creates challenges for displaying privacy policies
+ to users. Consider developing a _short form_ of the policy that
+ includes the most important information, and then provide a link to
+ the "long form" policy for those interested in more details. Several
+ groups are attempting to develop icon-based standards for
+ communicating privacy practices, which you may want to consider once
+ these standards mature.
+
+* __Collection of sensitive information__: An app's collection of
+ sensitive personal information raises important privacy concerns.
+ Examples of sensitive personal information include financial
+ information, health information, and information from or about
+ children. It also includes information gathered from certain sensors
+ and databases typically found on mobile devices and tablets, such as
+ geolocation information, contacts/phonebook, microphone/camera, and
+ stored pictures/videos. See the following documentation pages for
+ more information: [camera](cordova_camera_camera.md.html),
+ [capture](cordova_media_capture_capture.md.html),
+ [contacts](cordova_contacts_contacts.md.html), and
+ [geolocation](cordova_geolocation_geolocation.md.html). Generally,
+ you should obtain a user's express permission before collecting
+ sensitive information and, if possible, provide a control mechanism
+ that allows a user to easily change permissions. App operating
+ systems can help in some instances by presenting just-in-time dialog
+ boxes that ask for the user's permission before collection. In these
+ cases, be sure to take advantage of any opportunity to customize the
+ dialog box text to clarify how the app uses and, if applicable,
+ shares such information.
+
+* __Avoiding user surprise__: If your app collects or uses information
+ in a way that may be surprising to users in light of the primary
+ purpose of your app (for example, a music player that accesses
+ stored pictures), you should take similar steps as with the
+ collection of sensitive personal information. That is, you should
+ strongly consider the use of just-in-time dialog boxes to inform the
+ user about the collection or use of that information and, if
+ appropriate, provide a corresponding privacy control.
+
+* __Third party data collection or sharing__: If you app collects
+ information that is provided to another company--such as a social
+ networking platform or an ad network (for example, if your app
+ displays advertising)--you should inform your users of that
+ collection and sharing. At a minimum, your privacy policy should
+ describe the information collection and sharing and, if appropriate,
+ offer your users the ability to control or opt-out of such
+ collection or sharing.
+
+* __Collection limitation and security__: Your users entrust your app
+ with their information and they expect that you will take
+ appropriate security precautions to protect it. One of the best ways
+ to avoid security compromises of personal information is not to
+ collect the information in the first place unless your app has a
+ specific and legitimate business reason for the collection. For
+ information that does need to be collected, ensure that you provide
+ appropriate security controls to protect that information, whether
+ it is stored on the device or on your backend servers. You should
+ also develop an appropriate data retention policy that is
+ implemented within the app and on your backend servers.
+
+Following are some additional helpful mobile privacy guides for developers:
+
+* California Attorney General, [Privacy on the Go: Recommendations for the Mobile Ecosystem][1]
+
+* Center for Democracy & Technology, Future of Privacy Forum, [Best Practices for Mobile App Developers][2]
+
+* CTIA-The Wireless Association, [Best Practices and Guidelines for Location Based Services][3]
+
+* Federal Trade Commission, [Mobile Privacy Disclosures: Building Trust Through Transparency][4]
+
+* Future of Privacy Forum, [Application Privacy][5] Website
+
+[1]: http://oag.ca.gov/sites/all/files/pdfs/privacy/privacy_on_the_go.pdf
+[2]: http://www.futureofprivacy.org/wp-content/uploads/Best-Practices-for-Mobile-App-Developers_Final.pdf
+[3]: http://www.ctia.org/business_resources/wic/index.cfm/AID/11300
+[4]: http://www.ftc.gov/os/2013/02/130201mobileprivacyreport.pdf
+[5]: http://www.applicationprivacy.org
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/appdev/whitelist/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/appdev/whitelist/index.md b/docs/en/3.3.0/guide/appdev/whitelist/index.md
new file mode 100644
index 0000000..d734a3e
--- /dev/null
+++ b/docs/en/3.3.0/guide/appdev/whitelist/index.md
@@ -0,0 +1,168 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Whitelist Guide
+
+Domain whitelisting is a security model that controls access to
+external domains over which you application has no control. Cordova's
+default security policy allows access to any site. Before moving your
+application to production, you should formulate a whitelist and allow
+access to specific network domains and subdomains.
+
+Cordova adheres to the [W3C Widget Access][1] specification, which
+relies on the `<access>` element within the app's `config.xml` file to
+enable network access to specific domains. For projects that rely on
+the CLI workflow described in The Command-Line Interface, this file is
+located in the project's top-level `www` directory. Otherwise for
+platform-specific development paths, locations are listed in the
+sections below. (See the various Platform Guides for more information
+on each platform.)
+
+The following examples demonstrate whitelist syntax:
+
+* Access to [google.com][2]:
+
+ <access origin="http://google.com" />
+
+* Access to the secure [google.com][3] (`https://`):
+
+ <access origin="https://google.com" />
+
+* Access to the subdomain [maps.google.com][4]:
+
+ <access origin="http://maps.google.com" />
+
+* Access to all the subdomains on [google.com][2], for example
+ [mail.google.com][5] and [docs.google.com][6]:
+
+ <access origin="http://*.google.com" />
+
+* Access to _all_ domains, for example, [google.com][2] and
+ [developer.mozilla.org][7]:
+
+ <access origin="*" />
+
+ This is the default value for newly created CLI projects.
+
+## Amazon Fire OS Whitelisting
+
+Platform-specific whitelisting rules are found in
+`res/xml/config.xml`.
+
+## Android Whitelisting
+
+Platform-specific whitelisting rules are found in
+`res/xml/config.xml`.
+
+__NOTE__: On Android 2.3 and before, domain whitelisting only works
+for `href` hyperlinks, not referenced resources such as images and
+scripts. Take steps to avoid scripts from being injected into the
+application.
+
+Navigating to non-whitelisted domains via `href` hyperlink causes the
+page to open in the default browser rather than within the
+application. (Compare this to iOS's behavior noted below.)
+
+## iOS Whitelisting
+
+The platform's whitelisting rules are found in the named application
+directory's `config.xml` file.
+
+Origins specified without a protocol, such as `www.apache.org` rather
+than `http://www.apache.org`, default to all of the `http`, `https`,
+`ftp`, and `ftps` schemes.
+
+Wildcards on the iOS platform are more flexible than in the [W3C
+Widget Access][1] specification. For example, the following accesses
+all subdomains and top-level domains such as `.com` and `.net`:
+
+ <access origin="*.google.*" />
+
+Unlike the Android platform noted above, navigating to non-whitelisted
+domains via `href` hyperlink on iOS prevents the page from opening at
+all.
+
+## BlackBerry 10 Whitelisting
+
+The whitelisting rules are found in `www/config.xml`.
+
+BlackBerry 10's use of wildcards differs from other platforms in two
+ways:
+
+* Any content accessed by `XMLHttpRequest` must be declared
+ explicity. Setting `origin="*"` does not work in this case.
+ Alternatively, all web security may be disabled using the
+ `WebSecurity` preference described in BlackBerry Configuration:
+
+ <preference name="websecurity" value="disable" />
+
+* As an alternative to setting `*.domain`, set an additional
+ `subdomains` attribute to `true`. It should be set to `false` by
+ default. For example, the following allows access to `google.com`,
+ `maps.google.com`, and `docs.google.com`:
+
+ <access origin="http://google.com" subdomains="true" />
+
+ The following narrows access to `google.com`:
+
+ <access origin="http://google.com" subdomains="false" />
+
+ Specify access to all domains, including the local `file://`
+ protocol:
+
+ <access origin="*" subdomains="true" />
+
+(For more information on support, see BlackBerry's documentation on the
+[access element][8].)
+
+## iOS Changes in 3.1.0
+
+Prior to version 3.1.0, Cordova-iOS included some non-standard extensions to the domain whilelisting scheme supported by other Cordova platforms. As of 3.1.0, the iOS whitelist now conforms to the resource whitelist syntax described at the top of this document. If you upgrade from pre-3.1.0, and you were using these extensions, you may have to change your `config.xml` file in order to continue whitelisting the same set of resources as before.
+
+Specifically, these patterns need to be updated:
+
+- `apache.org` (no protocol): This would previously match `http`, `https`, `ftp`, and `ftps` protocols. Change to "`*://apache.org/*`" to include all protocols, or include a line for each protocol you need to support.
+
+- `http://apache.*` (wildcard at end of domain): This would previously match all top-level-domains, including all possible two-letter TLDs (but not useful domains like .co.uk). Include a line for each TLD which you actually control, and need to whitelist.
+
+- `h*t*://ap*he.o*g` (wildcards for random missing letters): These are no longer supported; change to include a line for each domain and protocol that you actually need to whitelist.
+
+## Windows Phone Whitelisting
+
+The whitelisting rules for Windows Phone 7 and 8 are found in the
+app's `config.xml` file.
+
+## Tizen Whitelisting
+
+Whitelisting rules are found in the app's `config.xml` file. The
+platform relies on the same `subdomains` attribute as the BlackBerry
+platform.
+(For more information on support, see Tizen's documentation on the
+[access element][9].)
+
+[1]: http://www.w3.org/TR/widgets-access/
+[2]: http://google.com
+[3]: https://google.com
+[4]: http://maps.google.com
+[5]: http://mail.google.com
+[6]: http://docs.google.com
+[7]: http://developer.mozilla.org
+[8]: https://developer.blackberry.com/html5/documentation/ww_developing/Access_element_834677_11.html
+[9]: https://developer.tizen.org/help/index.jsp?topic=%2Forg.tizen.web.appprogramming%2Fhtml%2Fide_sdk_tools%2Fconfig_editor_w3celements.htm
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/cli/index.md b/docs/en/3.3.0/guide/cli/index.md
new file mode 100644
index 0000000..7cf5bfc
--- /dev/null
+++ b/docs/en/3.3.0/guide/cli/index.md
@@ -0,0 +1,486 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+---
+
+# The Command-Line Interface
+
+This guide shows you how to create applications and deploy them to
+various native mobile platforms using the `cordova` command-line
+interface (CLI). This tool allows you to create new projects, build
+them on different platforms, and run on real devices or within emulators. The CLI
+is the main tool to use for the cross-platform workflow (See the Overview for a description
+of the various workflows.) However, you can also use the CLI to initialize project code, after
+which you use various platforms' SDKs and shell tools for continued development.
+
+## Prerequisites
+
+Before running any command-line tools, you need to install SDKs for
+each platform you wish to target.
+(See the Platform Guides for more details.)
+
+To add support or rebuild a project for any platform, you need to run
+the command-line interface from the same machine that supports the
+platform's SDK. The CLI supports the following combinations:
+
+* iOS (Mac)
+* Amazon Fire OS (Mac, Linux, Windows)
+* Android (Mac, Linux)
+* BlackBerry 10 (Mac, Linux, Windows)
+* Windows Phone 7 (Windows)
+* Windows Phone 8 (Windows)
+* Windows 8 (Windows)
+* Firefox OS (Mac, Linux, Windows)
+
+On the Mac, the command-line is available via the _Terminal_
+application. On the PC, it's available as _Command Prompt_ under
+_Accessories_.
+
+The more likely it is that you run the CLI from different machines,
+the more it makes sense to maintain a remote source code repository,
+whose assets you pull down to local working directories.
+
+To install the `cordova` command-line tool, follow these steps:
+
+1. Download and install [Node.js](http://nodejs.org/). Following
+ installation, you should be able to invoke `node` or `npm` on your
+ command line.
+
+1. Install the `cordova` utility. In Unix, prefixing the additional
+ `sudo` command may be necessary to install development utilities in
+ otherwise restricted directories:
+
+ $ sudo npm install -g cordova
+
+ The installation log may produce errors for any uninstalled
+ platform SDKs. Following installation, you should be able to run
+ `cordova` on the command line.
+
+ **NOTE**: The `-g` flag above tells npm to install cordova globally.
+ You may need to add the npm directory to your PATH in order to invoke
+ globally installed npm modules. On Windows, npm can usually be found at
+ `C:\Users\username\AppData\Roaming\npm` and on Unix at
+ `/usr/local/share/npm`.
+
+## Create the App
+
+Go to the directory where you maintain your source code, and run a
+command such as the following:
+
+ $ cordova create hello com.example.hello HelloWorld
+
+It may take some time for the command to complete, so be patient. Running
+the command with the ` -d` option displays information about its progress.
+
+The first argument specifies a _hello_ directory to be generated
+for your project. Its `www` subdirectory houses your application's
+home page, along with various resources under `css`, `js`, and `img`,
+which follow common web development file-naming conventions. The
+`config.xml` file contains important metadata needed to generate and
+distribute the application.
+
+The other two arguments are optional: the `com.example.hello` argument
+provides your project with a reverse domain-style identifier, and the
+`HelloWorld` provides the application's display text. You can edit
+both of these values later in the `config.xml` file.
+
+## Add Platforms
+
+All subsequent commands need to be run within the project's directory,
+or any subdirectories within its scope:
+
+ $ cd hello
+
+Before you can build the project, you need to specify a set of target
+platforms. Your ability to run these commands depends on whether your
+machine supports each SDK, and whether you have already installed each
+SDK. Run any of these from a Mac:
+
+ $ cordova platform add ios
+ $ cordova platform add amazon-fireos
+ $ cordova platform add android
+ $ cordova platform add blackberry10
+ $ cordova platform add firefoxos
+
+Run any of these from a Windows machine, where _wp_ refers to
+different versions of the Windows Phone operating system:
+
+ $ cordova platform add wp7
+ $ cordova platform add wp8
+ $ cordova platform add windows8
+ $ cordova platform add amazon-fireos
+ $ cordova platform add android
+ $ cordova platform add blackberry10
+ $ cordova platform add firefoxos
+
+Run this to check your current set of platforms:
+
+ $ cordova platforms ls
+
+(Note the `platform` and `platforms` commands are synonymous.)
+
+Run either of the following synonymous commands to remove a platform:
+
+ $ cordova platform remove blackberry10
+ $ cordova platform rm amazon-fireos
+ $ cordova platform rm android
+
+Running commands to add or remove platforms affects the contents of
+the project's _platforms_ directory, where each specified platform
+appears as a subdirectory. The _www_ source directory is reproduced
+within each platform's subdirectory, appearing for example in
+`platforms/ios/www` or `platforms/android/assets/www`. Because the CLI
+constantly copies over files from the source _www_ folder, you should only
+edit these files and not the ones located under the _platforms_ subdirectories.
+If you use version control software, you should add this source _www_ folder,
+along with the _merges_ folder, to your version control system. (More information
+about the _merges_ folder can be found in the Customize Each Platform section below.)
+
+**WARNING**: When using the CLI to build your application, you are strongly discouraged
+from editing any files in the `/platforms/` folder unless you know what you are doing
+or are specifically told otherwise in documentation. This is because the files in the
+`/platforms/` direcotry will be overwritten on prepare or plugin reinstallation.
+
+If you wish at this point, you can use an SDK such as Eclipse or Xcode
+to open the project you created. You will need to open the derivative set of assets
+from the `/platforms/` directory to develop with an SDK. This is because
+the SDK specific metadata files are stored within the appropriate `/platform/` subdirectory.
+(See the Platform Guides for information on how to develop applications within each IDE.)
+Use this approach if you simply want to initialize a project using the CLI and
+then switch to an SDK for native work.
+
+Read on if you wish to use the cross-platform workflow approach (the CLI) for the entire
+development cycle.
+
+## Build the App
+
+By default, the `cordova create` script generates a skeletal web-based
+application whose home page is the project's `www/index.html` file.
+Edit this application however you want, but any initialization should
+be specified as part of the `deviceready` event handler, referenced by
+default from `www/js/index.js`.
+
+Run the following command to iteratively build the project:
+
+ $ cordova build
+
+This generates platform-specific code within the project's `platforms`
+subdirectory. You can optionally limit the scope of each build to
+specific platforms:
+
+ $ cordova build ios
+
+The `cordova build` command is a shorthand for the following, which in
+this example is also targeted to a single platform:
+
+ $ cordova prepare ios
+ $ cordova compile ios
+
+In this case, once you run `prepare`, you can use Apple's Xcode SDK as
+an alternative to modify and compile the platform-specific code that
+Cordova generates within `platforms/ios`. You can use the same
+approach with other platforms' SDKs.
+
+## Test the App on an Emulator or Device
+
+SDKs for mobile platforms often come bundled with emulators that
+execute a device image, so that you can launch the app from the home
+screen and see how it interacts with many platform features. Run a
+command such as the following to rebuild the app and view it within a
+specific platform's emulator:
+
+ $ cordova emulate android
+
+Some mobile platforms emulate a particular device by default, such as
+the iPhone for iOS projects. For other platforms, you may need to
+first associate a device with an emulator.
+
+Note: Emulator support is currently not available for Amazon Fire OS
+
+(See the Platform Guides for details.)
+For example, you may first run the `android` command to launch the
+Android SDK, then run a particular device image, which launches it
+according to its default behavior:
+
+
+
+Following up with the `cordova emulate` command refreshes the emulator
+image to display the latest application, which is now available for
+launch from the home screen:
+
+
+
+Alternately, you can plug the handset into your computer and test the
+app directly:
+
+ $ cordova run android
+
+Before running this command, you need to set up the device for
+testing, following procedures that vary for each platform. In
+Android and Amazon Fire OS devices, you would have to enable a __USB debugging__ option on
+the device, and perhaps add a USB driver depending on your development
+environmnent.
+See Platform Guides for details on each platform's requirements.
+
+## Add Plugin Features
+
+When you build and view a new project, the default application that
+appears doesn't do very much. You can modify the app in many ways to
+take advantage of standard web technologies, but for the app to
+communicate closely with various device-level features, you need to
+add plugins that provide access to core Cordova APIs.
+
+A _plugin_ is a bit of add-on code that provides an interface to
+native components. You can design your own plugin interface, for
+example when designing a hybrid app that mixes a Cordova WebView with
+native components. (See Embedding WebViews and Plugin Development
+Guide for details.) More commonly, you would add a plugin to enable
+one of Cordova's basic device-level features
+detailed in the API Reference. A list of these plugins, including
+additional plugins provided by the community, can be found at
+[plugins.cordova.io](http://plugins.cordova.io/). You can use
+the CLI to search for plugins from this registry. For example,
+searching for `bar` and `code` produces a single result that matches
+both terms as case-insensitive substrings:
+
+ $ cordova plugin search bar code
+
+ com.phonegap.plugins.barcodescanner - Scans Barcodes
+
+Searching for only the `bar` term yields and additional result:
+
+ org.apache.cordova.statusbar - Cordova StatusBar Plugin
+
+The `cordova plugin add` command requires you to specify the
+repository for the plugin code. Please note that when you follow the
+Web Project Dev workflow and use the CLI, the CLI will take care of adding
+the plugin code to the appropriate place for each platform. (If you are following the
+Native Project Dev Workflow, you will have to add plugins using Plugman (guide link here),
+multiple times for each platform.)
+
+Here are examples of how you might use the CLI to add features to the app:
+
+* Basic device information (Device API):
+
+ $ cordova plugin add org.apache.cordova.device
+
+* Network Connection and Battery Events:
+
+ $ cordova plugin add org.apache.cordova.network-information
+ $ cordova plugin add org.apache.cordova.battery-status
+
+* Accelerometer, Compass, and Geolocation:
+
+ $ cordova plugin add org.apache.cordova.device-motion
+ $ cordova plugin add org.apache.cordova.device-orientation
+ $ cordova plugin add org.apache.cordova.geolocation
+
+* Camera, Media playback and Capture:
+
+ $ cordova plugin add org.apache.cordova.camera
+ $ cordova plugin add org.apache.cordova.media-capture
+ $ cordova plugin add org.apache.cordova.media
+
+* Access files on device or network (File API):
+
+ $ cordova plugin add org.apache.cordova.file
+ $ cordova plugin add org.apache.cordova.file-transfer
+
+* Notification via dialog box or vibration:
+
+ $ cordova plugin add org.apache.cordova.dialogs
+ $ cordova plugin add org.apache.cordova.vibration
+
+* Contacts:
+
+ $ cordova plugin add org.apache.cordova.contacts
+
+* Globalization:
+
+ $ cordova plugin add org.apache.cordova.globalization
+
+* Splashscreen:
+
+ $ cordova plugin add org.apache.cordova.splashscreen
+
+* Open new browser windows (InAppBrowser):
+
+ $ cordova plugin add org.apache.cordova.inappbrowser
+
+* Debug console:
+
+ $ cordova plugin add org.apache.cordova.console
+
+Use `plugin ls` (or `plugin list`, or `plugin` by itself) to view
+currently installed plugins. Each displays by its identifier:
+
+ $ cordova plugin ls # or 'plugin list'
+ [ 'org.apache.cordova.console' ]
+
+To remove a plugin, refer to it by the same identifier that appears in
+the listing. For example, here is how you would remove support for a
+debug console from a release version:
+
+ $ cordova plugin rm org.apache.cordova.console
+ $ cordova plugin remove org.apache.cordova.console # same
+
+You can batch-remove or add plugins by specifying more than one
+argument for each command:
+
+ $ cordova plugin add org.apache.cordova.console org.apache.cordova.device
+
+## Advanced Plugin Options
+
+When adding a plugin, several options allow you to specify from where
+to fetch the plugin. The examples above use a well-known
+`registry.cordova.io` registry, and the plugin is specified by the
+`id`:
+
+ $ cordova plugin add org.apache.cordova.console
+
+The `id` may also include the plugin's version number, appended after
+an `@` character. The `latest` version is an alias for the most recent
+version. For example:
+
+ $ cordova plugin add org.apache.cordova.console@latest
+ $ cordova plugin add org.apache.cordova.console@0.2.1
+
+If the plugin is not registered at `registry.cordova.io` but is located in
+another git repository, you can specify an alternate URL:
+
+ $ cordova plugin add https://github.com/apache/cordova-plugin-console.git
+
+The git example above fetches the plugin from the end of the master
+branch, but an alternate git-ref such as a tag or branch can be
+appended after a `#` character:
+
+ $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0
+
+If the plugin (and its `plugin.xml` file) is in a subdirectory within
+the git repo, you can specify it with a `:` character. Note that the
+`#` character is still needed:
+
+ $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir
+
+You can also combine both the git-ref and the subdirectory:
+
+ $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir
+
+Alternately, specify a local path to the plugin directory that
+contains the `plugin.xml` file:
+
+ $ cordova plugin add ../my_plugin_dir
+
+## Using _merges_ to Customize Each Platform
+
+While Cordova allows you to easily deploy an app for many different
+platforms, sometimes you need to add customizations. In that case,
+you don't want to modify the source files in various `www` directories
+within the top-level `platforms` directory, because they're regularly
+replaced with the top-level `www` directory's cross-platform source.
+
+Instead, the top-level `merges` directory offers a place to specify
+assets to deploy on specific platforms. Each platform-specific
+subdirectory within `merges` mirrors the directory structure of the
+`www` source tree, allowing you to override or add files as needed.
+For example, here is how you might uses `merges` to boost the default
+font size for Android and Amazon Fire OS devices:
+
+* Edit the `www/index.html` file, adding a link to an additional CSS
+ file, `overrides.css` in this case:
+
+ <link rel="stylesheet" type="text/css" href="css/overrides.css" />
+
+* Optionally create an empty `www/css/overrides.css` file, which would
+ apply for all non-Android builds, preventing a missing-file error.
+
+* Create a `css` subdirectory within `merges/android`, then add a
+ corresponding `overrides.css` file. Specify CSS that overrides the
+ 12-point default font size specified within `www/css/index.css`, for
+ example:
+
+ body { font-size:14px; }
+
+When you rebuild the project, the Android version features the custom
+font size, while others remain unchanged.
+
+You can also use `merges` to add files not present in the original
+`www` directory. For example, an app can incorporate a _back button_
+graphic into the iOS interface, stored in
+`merges/ios/img/back_button.png`, while the Android version can
+instead capture `backbutton` events from the corresponding hardware
+button.
+
+## Help Commands
+
+Cordova features a couple of global commands, which may help you if
+you get stuck or experience a problem. The `help` command displays
+all available Cordova commands and their syntax:
+
+ $ cordova help
+ $ cordova # same
+
+The `info` command produces a listing of potentially useful details,
+such as currently installed platforms and plugins, SDK versions for
+each platform, and versions of the CLI and `node.js`:
+
+ $ cordova info
+
+It both presents the information to screen and captures the output in
+a local `info.txt` file.
+
+__NOTE__: Currently, only details on iOS and Android platforms are
+available.
+
+## Updating Cordova and Your Project
+
+After installing the `cordova` utility, you can always update it to
+the latest version by running the following command:
+
+ $ sudo npm update -g cordova
+
+Use this syntax to install a specific version:
+
+ $ sudo npm install -g cordova@3.1.0
+
+Run `cordova -v` to see which version is currently running. Run the `npm
+info` command for a longer listing that includes the current version
+along with other available version numbers:
+
+ $ npm info cordova
+
+Cordova 3.0 is the first version to support the command-line interface
+described in this section. If you are updating from a version prior to
+3.0, you need to create a new project as described above, then copy
+the older application's assets into the top-level `www` directory.
+Where applicable, further details about upgrading to 3.0 are available
+in the Platform Guides. Once you upgrade to the `cordova`
+command-line interface and use `npm update` to stay current, the more
+time-consuming procedures described there are no longer relevant.
+
+Cordova 3.0+ may still require various changes to
+project-level directory structures and other dependencies. After you
+run the `npm` command above to update Cordova itself, you may need to
+ensure your project's resources conform to the latest version's
+requirements. Run a command such as the following for each platform
+you're building:
+
+ $ cordova platform update android
+ $ cordova platform update ios
+ ...etc.
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/hybrid/plugins/index.md b/docs/en/3.3.0/guide/hybrid/plugins/index.md
new file mode 100644
index 0000000..b8dd5ea
--- /dev/null
+++ b/docs/en/3.3.0/guide/hybrid/plugins/index.md
@@ -0,0 +1,211 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Plugin Development Guide
+
+A _plugin_ is a package of injected code that allows the Cordova webview within
+which your app renders to communicate with the native platform on
+which it runs. Plugins provide access to device and platform
+functionality that is ordinarily unavailable to web-based apps. All
+the main Cordova API features are implemented as plugins, and many
+others are available that enable features such as bar code scanners,
+NFC communication, or to tailor calendar interfaces.
+
+Plugins comprise a single JavaScript interface along with
+corresponding native code libraries for each supported platform. This
+section steps through a simple _echo_ plugin that passes a string from
+JavaScript to the native platform and back, one that you can use as a
+model to build far more complex features. This section discusses the
+basic plugin structure and the outward-facing JavaScript interface.
+For each corresponding native interface, see the list at the end of
+this section.
+
+In addition to these instructions, when preparing to write a plugin it
+is best to look over
+[existing plugins](https://github.com/apache/cordova-android/tree/master/framework/src/org/apache/cordova)
+for guidance.
+
+## Building a Plugin
+
+Application developers use the CLI's `plugin add` command (discussed
+in The Command-Line Interface) to apply a plugin to a project. The
+argument to that command is the URL for a _git_ repository containing
+the plugin code. This example implements Cordova's Device API:
+
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
+
+The plugin repository must feature a top-level `plugin.xml` manifest
+file. There are many ways to configure this file, details for which
+are available in the Plugin Specification. This abbreviated version of
+the `Device` plugin provides a simple example to use as a model:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+ id="org.apache.cordova.device" version="0.2.3">
+ <name>Device</name>
+ <description>Cordova Device Plugin</description>
+ <license>Apache 2.0</license>
+ <keywords>cordova,device</keywords>
+ <js-module src="www/device.js" name="device">
+ <clobbers target="device" />
+ </js-module>
+ <platform name="ios">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Device">
+ <param name="ios-package" value="CDVDevice"/>
+ </feature>
+ </config-file>
+ <header-file src="src/ios/CDVDevice.h" />
+ <source-file src="src/ios/CDVDevice.m" />
+ </platform>
+ </plugin>
+
+The top-level `plugin` tag's `id` attribute uses the same
+reverse-domain format to identify the plugin package as the apps to
+they're added. The `js-module` tag specifies the path to the common
+JavaScript interface. The `platform` tag specifies a corresponding
+set of native code, for the `ios` platform in this case. The
+`config-file` tag encapsulates a `feature` tag that is injected into
+the platform-specific `config.xml` file to make the platform aware of
+the additional code library. The `header-file` and `source-file` tags
+specify the path to the library's component files.
+
+## Validating a Plugin
+
+You can use the `plugman` utility to check whether the plugin installs
+correctly for each platform. Install `plugman` with the following
+[node](http://nodejs.org/) command:
+
+ $ npm install -g plugman
+
+You need an valid app source directory, such as the top-level `www`
+directory included in a default CLI-generated project as described in
+The Command-Line Interface. Make sure the app's `index.html` home
+page reference the name of the plugin's JavaScript interface, as if it
+were in the same source directory:
+
+ <script src="myplugin.js"></script>
+
+Then run a command such as the following to test whether iOS
+dependencies load properly:
+
+ $ plugman -platform ios /path/to/my/project/www /path/to/my/plugin
+
+For details on `plugman` options, see Using Plugman to Manage Plugins.
+For information on how to actually _debug_ plugins, see each
+platform's native interface listed at the bottom of this page.
+
+## The JavaScript Interface
+
+The JavaScript provides the front-facing interface, making it perhaps
+the most important part of the plugin. You can structure your
+plugin's JavaScript however you like, but you need to call
+`cordova.exec` to communicate with the native platform, using the
+following syntax:
+
+ cordova.exec(function(winParam) {},
+ function(error) {},
+ "service",
+ "action",
+ ["firstArgument", "secondArgument", 42, false]);
+
+Here is how each parameter works:
+
+- `function(winParam) {}`: A success callback function. Assuming your
+ `exec` call completes successfully, this function executes along
+ with any parameters you pass to it.
+
+- `function(error) {}`: An error callback function. If the operation
+ does not complete successfully, this function executes with an
+ optional error parameter.
+
+- `"service"`: The service name to call on the native side. This
+ corresponds to a native class, for which more information is
+ available in the native guides listed below.
+
+- `"action"`: The action name to call on the native side. This
+ generally corresponds to the native class method. See the native
+ guides listed below.
+
+- `[/* arguments */]`: An array of arguments to pass into the native
+ environment.
+
+## Sample JavaScript
+
+This example shows one way to implement the plugin's JavaScript
+interface:
+
+ window.echo = function(str, callback) {
+ cordova.exec(callback, function(err) {
+ callback('Nothing to echo.');
+ }, "Echo", "echo", [str]);
+ };
+
+In this example, the plugin attaches itself to the `window` object as
+the `echo` function, which plugin users would call as follows:
+
+ window.echo("echome", function(echoValue) {
+ alert(echoValue == "echome"); // should alert true.
+ });
+
+Look at the last three arguments to the `cordova.exec` function. The
+first calls the `Echo` _service_, a class name. The second requests
+the `echo` _action_, a method within that class. The third is an array
+of arguments containing the echo string, which is the `window.echo`
+function's the first parameter.
+
+The success callback passed into `exec` is simply a reference to the
+callback function `window.echo` takes. If the native platform fires
+the error callback, it simply calls the success callback and passes it
+a default string.
+
+## Native Interfaces
+
+Once you define JavaScript for your plugin, you need to complement it
+with at least one native implementation. Details for each platform are
+listed below, and each builds on the simple Echo Plugin example above:
+
+- Amazon Fire OS Plugins
+- Android Plugins
+- iOS Plugins
+- BlackBerry 10 Plugins
+- Windows Phone Plugins
+
+The Tizen platform does not support plugins.
+
+## Publishing Plugins
+
+Once you develop your plugin, you may want to publish and share it
+with the community. You can publish your plugin to the cordova
+registry (based on [`npmjs`](https://github.com/isaacs/npmjs.org)) or
+to any other `npmjs`-based registry. Other developers can install it
+automatically using either `plugman` or the Cordova CLI. (For details
+on each development path, see Using Plugman to Manage Plugins and The
+Command-Line Interface.)
+
+To publish a plugin you need to use the `plugman` tool and go through
+the following steps:
+
+ $ plugman adduser # that is if you don't have an account yet
+ $ plugman publish /path/to/your/plugin
+
+That is it!
+
+Running `plugman --help` lists other available registry-based
+commands.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/hybrid/webviews/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/hybrid/webviews/index.md b/docs/en/3.3.0/guide/hybrid/webviews/index.md
new file mode 100644
index 0000000..e08b25b
--- /dev/null
+++ b/docs/en/3.3.0/guide/hybrid/webviews/index.md
@@ -0,0 +1,36 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Embedding WebViews
+
+Cordova applications are ordinarily implemented as a browser-based
+_WebView_ within the native mobile platform. This section shows how,
+for supporting platforms, to create your own WebView components that
+make full use of Cordova APIs. You can then deploy these Cordova
+application components along with native components in a hybrid
+application.
+
+To deploy a WebView, you need to be familiar with each native
+programming environment. The following provides instructions for
+supported platforms:
+
+- Amazon Fire OS WebViews
+- Android WebViews
+- iOS WebViews
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/overview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/overview/index.md b/docs/en/3.3.0/guide/overview/index.md
new file mode 100644
index 0000000..b33e9f5
--- /dev/null
+++ b/docs/en/3.3.0/guide/overview/index.md
@@ -0,0 +1,139 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+---
+
+# Overview
+
+Cordova is an open-source mobile development framework. It allows you
+to use standard web technologies such as HTML5, CSS3, and JavaScript
+for cross-platform development, avoiding each mobile platforms' native
+development language. Applications execute within wrappers targeted
+to each platform, and rely on standards-compliant API bindings to
+access each device's sensors, data, and network status.
+
+Use Cordova if you are:
+
+* a mobile developer and want to extend an application across more
+ than one platform, without having to re-implement it with each
+ platform's language and tool set.
+
+* a web developer and want to deploy a web app that's packaged for
+ distribution in various app store portals.
+
+* a mobile developer interested in mixing native application
+ components with a _WebView_ (browser window) that can access
+ device-level APIs, or if you want to develop a plugin interface
+ between native and WebView components.
+
+## Basic Components
+
+Cordova applications rely on a common `config.xml` file that provides
+information about the app and specifies parameters affecting how it
+works, such as whether it responds to orientation shifts. This file
+adheres to the W3C's
+[Packaged Web App](http://www.w3.org/TR/widgets/),
+or _widget_, specification.
+
+The application itself is implemented as a web page, named
+_index.html_ by default, that references whatever CSS, JavaScript,
+images, media files, or other resources are necessary for it to run.
+The app executes as a _WebView_ within the native application wrapper,
+which you distribute to app stores. For the web app to interact with
+various device features the way native apps do, it must also reference
+a `cordova.js` file, which provides API bindings.
+
+The Cordova-enabled WebView may provide the application with its
+entire user interface. It can also be a component within a larger,
+hybrid application that mixes the WebView with native application
+components. Cordova provides a _plugin_ interface for these
+components to communicate with each other.
+
+## Development Paths
+
+As of version 3.0, you can use two basic workflows to create
+a mobile application. While you can accomplish the same
+thing using both workflows, certain tasks are better suited to using one workflow
+over the other. For this reason, you should understand both workflows so
+that you can use the best tool for the best situation.
+
+The two main workflows that are supported are the _Web Project Dev_ workflow and the _Native Platform Dev_ workflow.
+
+### Web Project Dev
+
+You can think of the first workflow as the _Web Project Dev_ workflow. You should use
+this workflow when you want to create a Cordova application that runs on
+as many mobile operating systems as possible with as little platform-specific
+development work as possible. This workflow came into existence with Cordova 3.0
+and the creation of the Cordova _Command-line Interface_ (CLI). The CLI abstracts
+away a lot of the functionality of lower-level shell scripts that take care of the
+details involved with building your app, such as copying your web assets into
+the correct folders for each mobile platform, making platform specific configuration
+changes, or running specific build scripts to generate application binaries. You can read
+more about the _Web Project Dev_ workflow in The Command-line Interface. Please note
+that often when people speak of the "CLI," they are talking about this _Web Project Dev_
+workflow.
+
+### Native Platform Dev
+
+The second workflow can be thought of as a _Native Platform Dev_ workflow. You should use it
+when you want to focus on building an application for a single platform and are
+interested in changing the lower-level platform details. While you can still use this workflow
+to build cross-platform apps, the lack of tools to abstract away the various build steps will
+make it more difficult. For example, you will have to use Plugman to
+install the same plugin once for each platform that you want to support. The
+benefit to using this _Native Platform Dev_ workflow is that it gives you access to the lower-level
+shell scripts to build and test the application, so if you are hacking on the native
+side of things, this workflow is the most efficient way to test your changes. This workflow
+is also appropriate if you want to use the CordovaWebView as a small part in a larger native
+application (See the Embedding WebViews guide.) You can read about this workflow in the different
+Shell Tool guides, for instance, Android Shell Tool Guide and iOS Shell Tool Guide.
+
+When first starting out, it might be easiest to use the _Web Project Dev_ workflow
+to create an application. (To install the CLI, see The Command-line Interface.)
+Depending on the set of platforms you wish to target, you can rely on
+the CLI for progressively greater shares of the development cycle:
+
+* In the most basic scenario, you can use the CLI simply to create a
+ new project that is populated with default configuration for you to
+ modify.
+
+* For many mobile platforms, you can also use the CLI to set up
+ additional project files required to compile within each SDK. For
+ this to work, you must install each targeted platform's SDK.
+ (See the Platform Guides for instructions.)
+ As indicated in the Platform Support table, you may need to
+ run the CLI on different operating systems depending on the targeted
+ platform.
+
+* For supporting platforms, the CLI can compile executible
+ applications and run them in an SDK-based device emulator.
+ For comprehensive testing, you can also generate application files
+ and install them directly on a device.
+
+At any point in the development cycle, you can switch to using more of the _Native Platform
+Dev_ workflow. The platform-specific SDK tools provided may provide a richer set of
+options. (See the Platform Guides for details about each platform's SDK tool set.)
+
+An SDK environment is more appropriate if you want implement a hybrid
+app that mixes web-based and native application components.
+You may use the command-line utility to initially generate the app, or
+iteratively thereafter to feed updated code to SDK tools. You may
+also build the app's configuration file yourself.
+(See The config.xml File for details.)
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/amazonfireos/config.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/amazonfireos/config.md b/docs/en/3.3.0/guide/platforms/amazonfireos/config.md
new file mode 100644
index 0000000..436d292
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/amazonfireos/config.md
@@ -0,0 +1,66 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Amazon Fire OS Configuration
+
+The `config.xml` file controls an app's basic settings that apply
+across each application and CordovaWebView instance. This section
+details preferences that only apply to Amazon Fire OS builds. See The
+config.xml File for information on global configuration options.
+
+- `KeepRunning` (boolean, defaults to `true`): Determines whether the
+ application stays running in the background even after a `pause`
+ event fires.
+
+ <preference name="KeepRunning" value="false"/>
+
+- `ErrorUrl`: Specifies an error page that displays in response to
+ standard HTTP errors in the 400-500 range. Place the specified file
+ in the top-level directory containing the home page and other web
+ assets.
+
+ <preference name="ErrorUrl" value="error.html"/>
+
+- `LoadingDialog`: Display a native dialog when loading the app. The
+ value's format is _Title, Message_
+
+ <preference name="LoadingDialog" value="Please wait, the app is loading"/>
+
+- `LoadingPageDialog`: Display a native dialog when loading sub-pages
+ within an app. The value's format is _Title, Message_
+
+ <preference name="LoadingPageDialog" value="Please wait, the data is loading"/>
+
+- `LoadUrlTimeoutValue` (number, default is `20000`): When loading a
+ page, the amount of time to wait before throwing a timeout error.
+ This example specifies 10 seconds rather than 20:
+
+ <preference name="LoadUrlTimeoutValue" value="10000"/>
+
+- `SplashScreen`: The name of the file minus its extension in the
+ `res/drawable` directory. Various assets must share this common
+ name in various subdirectories.
+
+ <preference name="SplashScreen" value="splash"/>
+
+- `SplashScreenDelay` (number, defaults to `5000`): The amount of
+ time the splash screen image displays.
+
+ <preference name="SplashScreenDelay" value="10000"/>
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/amazonfireos/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/amazonfireos/index.md b/docs/en/3.3.0/guide/platforms/amazonfireos/index.md
new file mode 100644
index 0000000..6c71051
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/amazonfireos/index.md
@@ -0,0 +1,145 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Amazon Fire OS Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Amazon Fire OS devices, such as the Kindle Fire HDX.
+
+See the following for more detailed platform-specific information:
+
+* Amazon Fire OS Configuration
+* Amazon Fire OS WebViews
+* Amazon Fire OS Plugins
+
+## Requirements and Support
+
+Developing Cordova apps for Amazon Fire OS requires the Android SDK and the Amazon WebView SDK. Check the requirements for these SDKs at the links below:
+
+* [Android SDK System](http://developer.android.com/sdk/)
+
+* [Amazon WebView SDK](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv)
+
+## Installation
+
+
+### Android SDK
+
+Install the Android SDK from
+[developer.android.com/sdk](http://developer.android.com/sdk/). You
+may be presented with a choice of where to install the SDK, otherwise
+move the downloaded `adt-bundle` tree to wherever you store
+development tools.
+
+For Cordova command-line tools to work, you need to include the SDK's
+`tools` and `platform-tools` directories in your PATH environment.
+
+On Mac, Linux or other Unix-like platforms, you can use a text editor to create or modify the
+`~/.bash_profile` file, adding a line such as the following, depending
+on where the SDK installs:
+
+ export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools
+
+This exposes SDK tools in newly opened terminal windows. Otherwise run
+this to make them available in the current session:
+
+ $ source ~/.bash_profile
+
+To modify the PATH environment on Windows 7:
+
+* Click on the __Start__ menu in the lower-left corner of the desktop,
+ right-click on __Computer__, then click __Properties__.
+
+* Click __Advanced System Settings__ in the column on the left.
+
+* In the resulting dialog box, press __Environment Variables__.
+
+* Select the __PATH__ variable and press __Edit__.
+
+* Append the following to the PATH based on where you installed the
+ SDK, for example:
+
+ ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools
+
+* Save the value and close both dialog boxes.
+
+You may also need to enable Java and Ant. Open a command prompt and
+type `java`, and also type `ant`. Append to the PATH whichever fail to
+run:
+
+ ;%JAVA_HOME%\bin;%ANT_HOME%\bin
+
+### Amazon WebView SDK
+
+Download the Amazon WebView SDK from the [Amazon Developer Portal](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv).
+
+* Create a `libs/` folder in `~/.cordova/lib/amazon-fireos/cordova/3.1.0/` folder.
+* Add the `awv_interface.jar` from the downloaded SDK to `~/.cordova/lib/amazon-fireos/cordova/3.1.0/libs/`
+
+
+## Open a Project in the SDK
+
+Use the `cordova` utility to set up a new project, as described in The
+Cordova The Command-line Interface. For example, in a source-code directory:
+
+ $ cordova create hello com.example.hello "HelloWorld"
+ $ cd hello
+ $ cordova platform add amazon-fireos
+ $ cordova build
+
+Once created, here's how to use the SDK to modify it:
+
+* Launch the __Eclipse__ application.
+
+* Select the __New Project__ menu item.
+
+* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__:
+ 
+
+* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/amazon-fireos` subdirectory.
+
+* Press __Finish__.
+
+Once the Eclipse window opens, a red __X__ may appear to indicate
+unresolved problems. If so, follow these additional steps:
+
+* Right-click on the project directory.
+
+* In the resulting __Properties__ dialog, select __Android__ from the navigation pane.
+
+* For the project build target, select the highest Android API level you have installed.
+
+* Click __OK__.
+
+* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project.
+
+## Deploy to Device
+
+To push an app directly to the device, make sure USB debugging is enabled on your device as described on the
+[Android Developer Site](http://developer.android.com/tools/device.html),
+and use a mini USB cable to plug it into your system.
+
+You can push the app to the device from the command line:
+
+ $ cordova run amazon-fireos
+
+Alternately within Eclipse, right-click the project and choose __Run
+As → Android Application__.
+
+__Note__: Currently, testing via an emulator is not supported for Amazon WebView based apps.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/amazonfireos/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/amazonfireos/plugin.md b/docs/en/3.3.0/guide/platforms/amazonfireos/plugin.md
new file mode 100644
index 0000000..3fc5ca9
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/amazonfireos/plugin.md
@@ -0,0 +1,100 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Amazon Fire OS Plugins
+
+Follow the instructions provided in the Android Plugins Guide for an overview of developing custom plugins.
+
+## Echo Amazon Fire OS Plugin Example
+
+To match the JavaScript interface's _echo_ feature described in
+Application Plugins, use the `plugin.xml` to inject a `feature`
+specification to the local platform's `config.xml` file:
+
+ <platform name="amazon-fireos">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Echo">
+ <param name="android-package" value="org.apache.cordova.plugin.Echo"/>
+ </feature>
+ </config-file>
+ </platform>
+
+Then add the following to the
+`src/org/apache/cordova/plugin/Echo.java` file:
+
+ package org.apache.cordova.plugin;
+
+ import org.apache.cordova.CordovaPlugin;
+ import org.apache.cordova.CallbackContext;
+
+ import org.json.JSONArray;
+ import org.json.JSONException;
+ import org.json.JSONObject;
+
+ /**
+ * This class echoes a string called from JavaScript.
+ */
+ public class Echo extends CordovaPlugin {
+
+ @Override
+ public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+ if (action.equals("echo")) {
+ String message = args.getString(0);
+ this.echo(message, callbackContext);
+ return true;
+ }
+ return false;
+ }
+
+ private void echo(String message, CallbackContext callbackContext) {
+ if (message != null && message.length() > 0) {
+ callbackContext.success(message);
+ } else {
+ callbackContext.error("Expected one non-empty string argument.");
+ }
+ }
+ }
+
+If you want to reuse Android Plugin code for the Amazon Fire OS platform then modify the plugin.xml to point to the `android` specific source file. For example,
+
+ <platform name="amazon-fireos">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Echo">
+ <param name="android-package" value="org.apache.cordova.plugin.Echo"/>
+ </feature>
+ </config-file>
+ <source-file src="src/android/Echo.java" target-dir="src/org/apache/cordova/plugin" />
+ </platform>
+
+If you want to write a customized plugin for the Amazon Fire OS platform then create a folder named `amazon` under your plugin src/ folder and modify the plugin.xml to point to the `amazon` specific source file. For example,
+
+ <platform name="amazon-fireos">
+ <config-file target="config.xml" parent="/*">
+ <feature name="Echo">
+ <param name="android-package" value="org.apache.cordova.plugin.Echo"/>
+ </feature>
+ </config-file>
+ <source-file src="src/amazon/Echo.java" target-dir="src/org/apache/cordova/plugin" />
+ </platform>
+
+## Using Amazon WebView in your plugin
+
+Cordova for Amazon Fire OS makes use of custom Amazon WebView that is built on the open-source Chromium project. It is GPU accelerated and optimized for fluid performance on Kindle Fire.
+
+To understand how to best use Amazon WebView in your project, check out the [Amazon Developer Portal](https://developer.amazon.com/sdk/fire/IntegratingAWV.html).
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/amazonfireos/webview.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/amazonfireos/webview.md b/docs/en/3.3.0/guide/platforms/amazonfireos/webview.md
new file mode 100644
index 0000000..f02bc84
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/amazonfireos/webview.md
@@ -0,0 +1,113 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Amazon Fire OS WebViews
+
+Beginning with 3.0.0, you can use Cordova as a component in Amazon Fire OS applications. Amazon Fire OS refers to this component as `CordovaWebView`. `CordovaWebView` extends Amazon WebView that is built on the open source Chromium Project. By leveraging this feature, your web apps can utilize the latest HTML5 web standards running in a modern web runtime engine.
+
+## Prerequisites
+
+* Cordova 3.0.0 or greater
+
+* Android SDK updated to the latest SDK
+
+* Amazon WebView SDK
+
+## Guide to using CordovaWebView in a Amazon Fire OS Project
+
+1. Download and expand the [Amazon WebView SDK](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv) , then copy the awv_interface.jar into `/framework/libs` directory. Create a libs/ folder if it doesn't exist.
+
+2. `cd` into `/framework` and run `ant jar` to build the cordova jar. It creates the .jar file formed as `cordova-3.3.0.jar` in the `/framework` directory.
+
+3. Edit your application's `main.xml` file (under `/res/layout`) to look like the following, with the `layout_height`, `layout_width` and `id` modified to suit your application:
+
+ <org.apache.cordova.CordovaWebView
+ android:id="@+id/tutorialView"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent" />
+
+4. Modify your activity so that it implements the `CordovaInterface`. You should implement the included methods. You may wish to copy them from `/framework/src/org/apache/cordova/CordovaActivity.java`, or implement them on your own. The code fragment below shows a basic application that uses the interface. Note how the referenced view id matches the `id` attribute specified in the XML fragment shown above:
+
+ public class CordovaViewTestActivity extends Activity implements CordovaInterface {
+ CordovaWebView cwv;
+ /* Called when the activity is first created. */
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+ cwv = (CordovaWebView) findViewById(R.id.tutorialView);
+ Config.init(this);
+ cwv.loadUrl(Config.getStartUrl());
+ }
+
+If you use the camera, you should also implement this:
+
+ @Override
+ public void setActivityResultCallback(CordovaPlugin plugin) {
+ this.activityResultCallback = plugin;
+ }
+ /**
+ * Launch an activity for which you would like a result when it finished. When this activity exits,
+ * your onActivityResult() method is called.
+ *
+ * @param command The command object
+ * @param intent The intent to start
+ * @param requestCode The request code that is passed to callback to identify the activity
+ */
+ public void startActivityForResult(CordovaPlugin command, Intent intent, int requestCode) {
+ this.activityResultCallback = command;
+ this.activityResultKeepRunning = this.keepRunning;
+
+ // If multitasking turned on, then disable it for activities that return results
+ if (command != null) {
+ this.keepRunning = false;
+ }
+
+ // Start activity
+ super.startActivityForResult(intent, requestCode);
+ }
+
+ @Override
+ /**
+ * Called when an activity you launched exits, giving you the requestCode you started it with,
+ * the resultCode it returned, and any additional data from it.
+ *
+ * @param requestCode The request code originally supplied to startActivityForResult(),
+ * allowing you to identify who this result came from.
+ * @param resultCode The integer result code returned by the child activity through its setResult().
+ * @param data An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
+ */
+ protected void onActivityResult(int requestCode, int resultCode, Intent intent) {
+ super.onActivityResult(requestCode, resultCode, intent);
+ CordovaPlugin callback = this.activityResultCallback;
+ if (callback != null) {
+ callback.onActivityResult(requestCode, resultCode, intent);
+ }
+ }
+
+Finally, remember to add the thread pool, otherwise the plugins have no threads to run on:
+
+ @Override
+ public ExecutorService getThreadPool() {
+ return threadPool;
+ }
+
+6. Copy your application's HTML and JavaScript files to your Amazon Fire OS project's `/assets/www` directory.
+
+7. Copy `config.xml` from `/framework/res/xml` to your project's `/res/xml` directory.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/android/config.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/android/config.md b/docs/en/3.3.0/guide/platforms/android/config.md
new file mode 100644
index 0000000..f8c6d80
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/android/config.md
@@ -0,0 +1,55 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Configuration
+
+The `config.xml` file controls an app's basic settings that apply
+across each application and CordovaWebView instance. This section
+details preferences that only apply to Android builds. See The
+config.xml File for information on global configuration options.
+
+- `KeepRunning` (boolean, defaults to `true`): Determines whether the
+ application stays running in the background even after a `pause`
+ event fires. Note: setting this to false will not kill the app after
+ a pause event, it will only halt execution of code in the cordova
+ webview while the app is in the background.
+
+ <preference name="KeepRunning" value="false"/>
+
+- `LoadUrlTimeoutValue` (number, default to `20000`, 20 seconds): When loading a
+ page, the amount of time to wait before throwing a timeout error.
+ This example specifies 10 seconds rather than 20:
+
+ <preference name="LoadUrlTimeoutValue" value="10000"/>
+
+- `SplashScreen`: The name of the file minus its extension in the
+ `res/drawable` directory. Various assets must share this common
+ name in various subdirectories.
+
+ <preference name="SplashScreen" value="splash"/>
+
+- `SplashScreenDelay` (number, defaults to `5000`): The amount of
+ time the splash screen image displays.
+
+ <preference name="SplashScreenDelay" value="10000"/>
+
+- `InAppBrowserStorageEnabled` (boolean, defaults to `true`): Controls
+ whether pages opened within an InAppBrowser can access the same
+ localStorage and WebSQL storage as pages opened with the default
+ browser.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/c6219cfc/docs/en/3.3.0/guide/platforms/android/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.3.0/guide/platforms/android/index.md b/docs/en/3.3.0/guide/platforms/android/index.md
new file mode 100644
index 0000000..039294b
--- /dev/null
+++ b/docs/en/3.3.0/guide/platforms/android/index.md
@@ -0,0 +1,217 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Android devices. It walks you through the process
+of installing the Android SDK, opening an Android project in Eclipse SDK,
+and deploying to an emulator or device. You will need to follow this guide
+to at least Install the Android SDK, regardless of which workflow you
+are following. (Both the _Web Project Dev_ and _Native Platform Dev_ workflows
+require the Android SDK to be installed and accessable via your PATH.)
+
+See the following for more detailed platform-specific information:
+
+* Android Configuration
+* Android WebViews
+* Android Plugins
+* Upgrading Android
+* Android Command-line Tools
+
+The command-line tools above refer to versions prior to Cordova 3.0.
+See The Command-Line Interface for information about the
+current interface.
+
+## Requirements and Support
+
+See the [System Requirements](http://developer.android.com/sdk/index.html)
+for the Android SDK.
+
+Cordova supports Android 2.2, 2.3, and 4.x. As a general rule,
+platforms are deprecated as they dip below 5% on Google's
+[distribution dashboard](http://developer.android.com/about/dashboards/index.html).
+
+<!--
+NOTE, doc said:
+- Android 2.1 (Deprecated May 2013)
+- Android 3.x (Deprecated May 2013)
+-->
+
+Developers should use the `cordova` utility in conjunction with
+the Android SDK. See The Command-Line Interface for
+information how to install it, add projects, then build and deploy a
+project.
+
+Install the Android SDK from
+[developer.android.com/sdk](http://developer.android.com/sdk/). The android sdk
+is distributed as an 'adt-bundle-<os>-<arch>-<ver>' file.
+On windows, the adt-bundle is packaged with an installer.
+On OSX and Linux, simply unpack the 'adt-bundle' in the location you store development tools.
+[More detailed information on Android SDK setup can be found here](http://developer.android.com/sdk/installing/bundle.html)
+
+
+For Cordova command-line tools to work, you need to include the SDK's
+`tools` and `platform-tools` directories in your PATH environment. On
+Mac, you can use a text editor to create or modify the
+`~/.bash_profile` file, adding a line such as the following, depending
+on where the SDK installs:
+
+ export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools
+
+This exposes SDK tools in newly opened terminal windows. Otherwise run
+this to make them available in the current session:
+
+ $ source ~/.bash_profile
+
+To modify the PATH environment on Windows 7:
+
+* Click on the __Start__ menu in the lower-left corner of the desktop,
+ right-click on __Computer__, then click __Properties__.
+
+* Click __Advanced System Settings__ in the column on the left.
+
+* In the resulting dialog box, press __Environment Variables__.
+
+* Select the __PATH__ variable and press __Edit__.
+
+* Append the following to the PATH based on where you installed the
+ SDK, for example:
+
+ ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools
+
+* Save the value and close both dialog boxes.
+
+You may also need to enable Java and Ant. Open a command prompt and
+type `java`, and also type `ant`. Append to the PATH whichever fail to
+run:
+
+ ;%JAVA_HOME%\bin;%ANT_HOME%\bin
+
+## Open a Project in the SDK
+
+Use the `cordova` utility to set up a new project, as described in The
+Cordova The Command-Line Interface. For example, in a source-code directory:
+
+ $ cordova create hello com.example.hello "HelloWorld"
+ $ cd hello
+ $ cordova platform add android
+ $ cordova build
+
+Once created, here's how to use the SDK to modify it:
+
+* Launch the __Eclipse__ application.
+
+* Select the __New Project__ menu item.
+
+* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__:
+ 
+
+* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/android` subdirectory.
+
+* Press __Finish__.
+
+Once the Eclipse window opens, a red __X__ may appear to indicate
+unresolved problems. If so, follow these additional steps:
+
+* Right-click on the project directory.
+
+* In the resulting __Properties__ dialog, select __Android__ from the navigation pane.
+
+* For the project build target, select the highest Android API level you have installed.
+
+* Click __OK__.
+
+* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project.
+
+## Deploy to Emulator
+
+You can use the `cordova` utility to run an app in an emulator, or you
+can run it within the SDK. Either way, the SDK must first be
+configured to display at least one device. To do so, use the Android
+SDK Manager, a Java application that runs separately from Eclipse.
+There are two ways to open it:
+
+* Run `android` on the command line.
+
+* From within Eclipse, press this toolbar icon:
+
+ 
+
+Once open, the Android SDK Manager displays various runtime libraries:
+
+
+
+Choose __Tools → Manage AVDs__ (Android Virtual Devices), then
+choose any item from __Device Definitions__ in the resulting dialog
+box:
+
+
+
+Press __Create AVD__, optionally modifying the name, then press __OK__
+to accept the changes:
+
+
+
+The AVD then appears in the __Android Virtual Devices__ list:
+
+
+
+To open the emulator as a separate application, select the AVD and
+press __Start__. It launches much as it would on the device, with
+additional controls available for hardware buttons:
+
+
+
+At this point you can use the `cordova` utility to deploy the
+application to the emulator from the command line:
+
+ $ cordova emulate android
+
+If instead you work within Eclipse, right-click the project and
+choose __Run As → Android Application__. You may be asked to
+specify an AVD if none are already open.
+
+For a faster experience, use an Intel-based emulator image:
+
+* Install one or more `Intel x86 Atom` System Images as well as the
+ `Intel Hardware Accelerated Execution Manager`, available under
+ __Extras__.
+
+* Run the Intel installer, which is available within your Android SDK
+ at `extras/intel/Hardware_Accelerated_Execution_Manager`.
+
+* Create a new AVD with the target set to an Intel image.
+
+* When starting the emulator, ensure there are no error messages
+ indicating a failure to load HAX modules.
+
+## Deploy to Device
+
+To push an app directly to the device, make sure USB debugging is
+enabled on your device as described on the
+[Android Developer Site](http://developer.android.com/tools/device.html),
+and use a mini USB cable to plug it into your system.
+
+You can push the app to the device from the command line:
+
+ $ cordova run android
+
+Alternately within Eclipse, right-click the project and choose __Run
+As → Android Application__.