http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/amazonfireos/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/amazonfireos/index.md b/www/docs/en/dev/guide/platforms/amazonfireos/index.md new file mode 100644 index 0000000..055f249 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/amazonfireos/index.md @@ -0,0 +1,195 @@ +--- +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. + +title: Amazon Fire OS Platform Guide +--- + +# 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](config.html) +* [Amazon Fire OS WebViews](webview.html) +* [Amazon Fire OS Plugins](plugin.html) + +## Introduction + +By targeting the Amazon Fire OS platform, Cordova developers can create hybrid web apps that take advantage of the advanced web engine integrated into Kindle Fire devices. Amazon WebView API (AWV) is a Chromium-derived web runtime exclusive to Fire OS. A drop-in replacement for the WebView that comes with Android devices, AWV makes it possible to create better performing and more powerful hybrid web apps by providing support for a faster JavaScript engine (V8), remote debugging, and hardware optimizations for Kindle Fire devices including an accelerated 2D Canvas, and access to HTML5 features not supported by Androidâs built in WebView such as: CSS Calc, Form Validation, getUserMedia, IndexedDB, Web Workers, WebSockets and WebGL. + +For more information about the Amazon WebView API, please see the Amazon Developer Portal's [HTML5 Hybrid Apps page](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app). For questions about getting started and other support issues, please see the Amazon Developer Portal [Forums - HTML5 Hybrid Apps](http://forums.developer.amazon.com/forums/category.jspa?categoryID=41). + + +## Requirements and Support + +Developing Cordova apps for Amazon Fire OS requires installation of a variety of support files, including everything needed for Android development, as well as the Amazon WebView SDK. Check the list below for the required installs: + +* [The Command-Line Interface](../../cli/index.html) +* [Android SDK](http://developer.android.com/sdk/) +* [Apache Ant](http://ant.apache.org) +* [Amazon WebView SDK](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app) + +## Installation + + +### Android SDK and Apache Ant + +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. + +You'll need to run the Android SDK Manager (`android` from a command line) at least once before starting your Cordova project. Make sure to install the most recent version of the Android SDK Tools and SDK Platform **specifically API level 19**. Please see [Setting up your Development Environment](https://developer.amazon.com/public/resources/development-tools/ide-tools/tech-docs/01-setting-up-your-development-environment) on the Amazon Developer Portal for more information about setting up your development environment for Kindle Fire OS devices. + +Install the Apache Ant build tool by [downloading an Ant binary distribution](http://ant.apache.org/bindownload.cgi), unzipping into a directory you can refer to later. See the [Ant manual](http://ant.apache.org/manual/index.html) for more info. + +For Cordova command-line tools to work, you need to include the Android SDK's +`tools`, `platform-tools` and `apache-ant/bin` directories in your PATH environment. + +#### Mac/Linux Path + +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 and Ant are installed: + + export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools:/Development/apache-ant/bin + +This exposes SDK tools in newly opened terminal windows. Otherwise run +this to make them available in the current session: + + $ source ~/.bash_profile + +#### Windows Path + +To modify the PATH environment on Windows: + +* 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 and Ant, for example: + + ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools;C:\Development\apache-ant\bin + +* Save the value and close both dialog boxes. + +* You will also need to enable Java. Open a command prompt and +type `java`, if it does not run, append the location of the Java binaries to your PATH as well. Make sure %JAVA_HOME% is pointing to installed JDK directory. You might have to add JAVA_HOME environment variable seperately. + + ;%JAVA_HOME%\bin + + +### Amazon WebView SDK + +In order to create Cordova apps using the Amazon Fire OS platform target, you'll need to download, unpack and install the Amazon WebView SDK support files. This step will only need to be done for your first Amazon Fire OS project. + +* Download the Amazon WebView SDK from the [Amazon Developer Portal](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app). + +* Copy `awv_interface.jar` from the downloaded SDK to Cordova's working directory. Create commonlibs(shown below) folder if it doesn't exist: + + **Mac/Linux:** + `~/.cordova/lib/commonlibs/` + + **Windows:** + `%USERPROFILE%\.cordova\lib\commonlibs` + + +## Create New Project for Amazon Fire OS + +Use the `cordova` utility to set up a new project, as described in The +Cordova [The Command-Line Interface](../../cli/index.html). For example, in a source-code directory: + + $ cordova create hello com.example.hello "HelloWorld" + $ cd hello + $ cordova platform add amazon-fireos + $ cordova build + +***Note:*** The first time the amazon-fireos platform is installed on your system, it will download the appropriate files to the Cordova working directory, but will then fail as it is missing the AWV SDK support files (see above). Follow the instructions above to install the `awv_interface.jar`, then remove and re-add the amazon-fireos platform to your project. This step will only need to be done for first Amazon Fire OS 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, additionally the Amazon WebView API is only available on Fire OS devices. For more information, please see the [Amazon WebView API SDK](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app) documentation. + +### Run Flags + +The run command accepts optional parameters as specified in the Cordova Command Line Interface document, Fire OS also accepts an additional `--debug` flag which will enable Chromium's Developer Tools for remote web debugging. + +To use Developer Tools, enter: + + $ cordova run --debug amazon-fireos + +This will enable the tools on the running client. You can then connect to the client by port forwarding using the Android Debug Bridge (adb) referring to the app's package name. + +For example: + + adb forward tcp:9222 localabstract:com.example.helloworld.devtools + +You can then use the DevTools via a Chromium-based browser by navigating to: `http://localhost:9222`. + +### Optional Eclipse support + +Once created, you can use the Eclipse that comes along with the Android SDK to modify the project. Beware that modifications made through Eclipse will be overwritten if you continue to use Cordova command line tools. + +* 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. + +* Eclipse will show you hello and hello-CorddovaLib - 2 projects to be added. Add both. + +* 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 (currently API Level 19) you have installed. + +* Click __OK__. + +* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project. +
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/amazonfireos/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/amazonfireos/plugin.md b/www/docs/en/dev/guide/platforms/amazonfireos/plugin.md new file mode 100644 index 0000000..d4fdac4 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/amazonfireos/plugin.md @@ -0,0 +1,103 @@ +--- +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. + +title: Amazon Fire OS Plugins +--- + +# Amazon Fire OS Plugins + +Follow the instructions provided in the [Android Plugins](../android/plugin.html) 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/f061b980/www/docs/en/dev/guide/platforms/amazonfireos/webview.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/amazonfireos/webview.md b/www/docs/en/dev/guide/platforms/amazonfireos/webview.md new file mode 100644 index 0000000..4c018e5 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/amazonfireos/webview.md @@ -0,0 +1,130 @@ +--- +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. + +title: Amazon Fire OS WebViews +--- + +# Amazon Fire OS WebViews + +Beginning with 3.3.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. + +If you're unfamiliar with Amazon Fire OS, you should first familiarize +yourself with the [Amazon Fire OS Platform Guide](index.html) and have the latest SDKs installed before you attempt the more unusual development option of embedding a WebView. + +## Prerequisites + +* Cordova 3.3.0 or greater + +* Android SDK updated to the latest SDK + +* Amazon WebView SDK + +## Guide to using CordovaWebView in a Amazon Fire OS Project + +1. To follow these instructions, make sure you have the latest Cordova + distribution. Download it from + [cordova.apache.org](http://cordova.apache.org) and unzip its + Amazon Fire OS package. + +2. 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. + +3. Navigate to the package's `/framework` directory and run + `ant jar`. It creates the Cordova `.jar` file, formed as + `/framework/cordova-x.x.x.jar`. + +4. Copy the `.jar` file into the Android project's `/libs` directory. + +5. Add the following to the application's `/res/xml/main.xml` file, + with the `layout_height`, `layout_width` and `id` modified to suit + the application: + + <org.apache.cordova.CordovaWebView + android:id="@+id/tutorialView" + android:layout_width="match_parent" + android:layout_height="match_parent" /> + +6. 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; + } + +7. Copy your application's HTML and JavaScript files to your Amazon Fire OS project's `/assets/www` directory. + +8. 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/f061b980/www/docs/en/dev/guide/platforms/android/config.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/config.md b/www/docs/en/dev/guide/platforms/android/config.md new file mode 100644 index 0000000..6a120ad --- /dev/null +++ b/www/docs/en/dev/guide/platforms/android/config.md @@ -0,0 +1,125 @@ +--- +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. + +title: Android Configuration +--- + +# 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](config_ref_index.md.html#The%20config.xml%20File) for information on global configuration options. + +- `KeepRunning` (boolean, defaults to `true`): Determines whether the + application stays running in the background even after a `[pause](../../../cordova/events/events.pause.html)` + event fires. Setting this to `false` does not kill the app after a + `[pause](../../../cordova/events/events.pause.html)` event, but simply halts execution of code within the cordova + webview while the app is in the background. + + <preference name="KeepRunning" value="false"/> + +- `LoadUrlTimeoutValue` (number in milliseconds, 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` (string, defaults to `splash`): 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="mySplash"/> + +- `SplashScreenDelay` (number in milliseconds, defaults to `3000`): 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. + + <preference name="InAppBrowserStorageEnabled" value="true"/> + +- `LoadingDialog` (string, defaults to `null`): If set, displays a dialog with + the specified title and message, and a spinner, when loading the first + page of an application. The title and message are separated by a comma + in this value string, and that comma is removed before the dialog is + displayed. + + <preference name="LoadingDialog" value="My Title,My Message"/> + +- `LoadingPageDialog` (string, defaults to `null`): The same as `LoadingDialog`, + but for loading every page after the first page in the application. + + <preference name="LoadingPageDialog" value="My Title,My Message"/> + +- `ErrorUrl` (URL, defaults to `null`): + If set, will display the referenced page upon an error in the application + instead of a dialog with the title "Application Error". + + <preference name="ErrorUrl" value="myErrorPage.html"/> + +- `ShowTitle` (boolean, defaults to `false`): Show the title at the top + of the screen. + + <preference name="ShowTitle" value="true"/> + +- `LogLevel` (string, defaults to `ERROR`): Sets the minimum log level + through which log messages from your application will be filtered. Valid + values are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `VERBOSE`. + + <preference name="LogLevel" value="VERBOSE"/> + +- `SetFullscreen` (boolean, defaults to `false`): Same as the `Fullscreen` + parameter in the global configuration of this xml file. This Android-specific + element is deprecated in favor of the global `Fullscreen` element, and will + be removed in a future version. + +- `AndroidLaunchMode` (string, defaults to `singleTop`): Sets the Activity + `android:launchMode` attribute. This changes what happens when the app is + launched from app icon or intent and is already running. + Valid values are `standard`, `singleTop`, `singleTask`, `singleInstance`. + + <preference name="AndroidLaunchMode" value="singleTop"/> + +- `DefaultVolumeStream` (string, defaults to `default`, added in cordova-android 3.7.0): Sets which volume + the hardware volume buttons link to. By default this is "call" for phones + and "media" for tablets. Set this to "media" to have your app's volume + buttons always change the media volume. Note that when using Cordova's + media plugin, the volume buttons will dynamically change to controlling + the media volume when any Media objects are active. + +- `OverrideUserAgent` (string, not set by default): + If set, the value will replace the old UserAgent of webview. + It is helpful to identify the request from app/browser when requesting remote pages. + Use with caution, this may causes compitiable issue with web servers. + For most cases, use AppendUserAgent instead. + + <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" /> + +- `AppendUserAgent` (string, not set by default): + If set, the value will append to the end of old UserAgent of webview. + When using with OverrideUserAgent, this value will be ignored. + + <preference name="AppendUserAgent" value="My Browser" /> + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/android/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/index.md b/www/docs/en/dev/guide/platforms/android/index.md new file mode 100644 index 0000000..4f97111 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/android/index.md @@ -0,0 +1,307 @@ +--- +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. + +title: Android Platform Guide +--- + +# Android Platform Guide + +This guide shows how to set up your SDK environment to deploy Cordova +apps for Android devices, and how to optionally use Android-centered +command-line tools in your development workflow. You need to install +the Android SDK regardless of whether you want to use these +platform-centered shell tools or cross-platform Cordova CLI for +development. For a comparison of the two development paths, see the +[Overview](../../overview/index.html). For details on the CLI, see [The Command-Line Interface](../../cli/index.html). + +## Requirements and Support + +Cordova for Android requires the Android SDK which could be installed +on OS X, Linux or Windows operation system. See the Android SDK's +[System Requirements](http://developer.android.com/sdk/index.html#Requirements). + +Cordova supports Android 4.0.x (starting with Android API level 14) +and higher. As a general rule, Android versions become unsupported by Cordova as +they dip below 5% on Google's +[distribution dashboard](http://developer.android.com/about/dashboards/index.html). +Android versions earlier than API level 10, and the 3.x versions (Honeycomb, +API levels 11-13) fall significantly below that 5% threshold. + +## Install Cordova Shell Tools + +If you want to use Cordova's Android-centered shell tools in +conjunction with the SDK, download Cordova from +[cordova.apache.org](http://cordova.apache.org). Otherwise ignore this +section if you plan to use the cross-platform CLI tool described in +[The Command-Line Interface](../../cli/index.html). + +The Cordova download contains separate archives for each platform. Be +sure to expand the appropriate archive, `android` in this case, within +an empty directory. The relevant executible utilities are available +in the top-level `bin` directory. (Consult the __README__ file if +necessary for more detailed directions.) + +These shell tools allow you to create, build, and run Android apps. +For information on the additional command-line interface that enables +plugin features across all platforms, see Using Plugman to Manage +Plugins. See Application Plugins for details on how to develop +plugins. + +## Install the Java Development Kit (JDK) + +Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html) +or later. + +When installing on Windows you also need to set `JAVA_HOME` Environment Variable +according to JDK installation path (for example, C:\Program Files\Java\jdk1.7.0_75). + +## Install the Android SDK + +Install the [Android Stand-alone SDK Tools](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio). Procceed with `Android Studio` if you plan +developing new Cordova for Android plugins or using native tools to +run and debug Android platform. Otherwise, `Android Stand-alone SDK Tools` +are enough to build and deploy Android application. + +Detailed installation instructions are available as part of installation +links above. + +For Cordova command-line tools to work, or the CLI that is based upon +them, you need to include the SDK's `tools` and `platform-tools` +directories in your `PATH`. On a Mac or Linux, 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/android-sdk/platform-tools:/Development/android-sdk/tools + +This line in `~/.bash_profile` exposes these tools in newly opened terminal +windows. If your terminal window is already open in OSX, or to avoid a logout/login +on Linux, run this to make them available in the current terminal window: + + $ source ~/.bash_profile + +To modify the `PATH` environment on Windows: + +1. Click on the __Start__ menu in the lower-left corner of the desktop, + right-click on __Computer__, then select __Properties__. + +1. Select __Advanced System Settings__ in the column on the left. + +1. In the resulting dialog box, press __Environment Variables__. + +1. Select the __PATH__ variable and press __Edit__. + +1. Append the following to the `PATH` based on where you installed the + SDK, for example: + + ;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools + +1. Save the value and close both dialog boxes. + +## Install SDK Packages + +Open Android SDK Manager (for example, via terminal: `android`) and install: + +1. Android 5.1.1 (API 22) platform SDK +1. Android SDK Build-tools version 19.1.0 or higher +1. Android Support Repository (Extras) + +See [Installing SDK Packages](http://developer.android.com/sdk/installing/adding-packages.html) +for more details. + +## Configure an Emulator + +Android sdk doesn't provide any default emulator instance by default. You can +create a new one by running `android` on the command line. +The press __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: + + + + +For a faster experience, you can use the `Virtual Machine Acceleration` to improve +the execution speed. +Many modern CPUs provide extensions to execute Virtual Machines more efficiently. +Before attempting to use this type of acceleration, you need to determine if your +current development system's CPU, supports one the following virtualization technologies: + +* __Intel Virtualization Technology__ (VT-x, vmx) → [Intel VT-x supported processor list](http://ark.intel.com/products/virtualizationtechnology) +* __AMD Virtualization__ (AMD-V, SVM), only supported for Linux (Since May 2006, all CPUs AMD include AMD-V, except Sempron). + +Another way to find out if your Intel processor supports VT-x Technology, it's by executing the +`Intel Processor Identification Utility`, for `Windows`you can download it from the Intel [Download Center](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7838), +or you can use the [booteable utility](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7840&lang=eng), which is `OS Independent`. + +After install and execute the `Intel Processor Identification Utility` over Windows, you will get the following window, +in order to check if your CPU supports the Virtualization Technologies: + + + +In order to speed up the emulator, you need to download and install one or more `Intel x86 Atom` System Images, +as well as the `Intel Hardware Accelerated Execution Manager (HAXM)`. + +Open your Android SDK Manager, and select the `Intel x86 Atom` System Image, for whichever version that you want to test. Then go to `Extras` +and select `Intel x86 Emulator Accelerator (HAXM)`, and install those packages: + + + +After download, run the Intel installer, which is available within your +Android SDK at `extras/intel/Hardware_Accelerated_Execution_Manager`. +__Note__:`If you have any problems installing the package, you can find more information and step by step guidance check this` +[Intel Article](http://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture). + +1. Install one or more `Intel x86 Atom` System Images as well as the + `Intel Hardware Accelerated Execution Manager`, available under + __Extras__. + +1. Run the Intel installer, which is available within your Android SDK + at `extras/intel/Hardware_Accelerated_Execution_Manager`. + +1. Create a new AVD with the target set to an Intel image. + +1. When starting the emulator, ensure there are no error messages + indicating a failure to load HAX modules. + +## Create a New Project + +At this point, to create a new project you can choose between the +cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html), or +the set of Android-specific shell tools. From within a source-code +directory, here's the CLI approach: + + $ cordova create hello com.example.hello HelloWorld + $ cd hello + $ cordova platform add android + $ ccordova prepare # or "cordova build" + +Here's the corresponding lower-level shell-tool approach for both Unix +and Windows: + + $ /path/to/cordova-android/bin/create /path/to/new/hello com.example.hello HelloWorld + C:\path\to\cordova-android\bin\create.bat C:\path\to\new\hello com.example.hello HelloWorld + +## Build the Project + +If you are using the CLI in development, the project directory's +top-level `www` directory contains the source files. Run any of +these within the project directory to rebuild the app: + + $ cordova build # build all platforms that were added + $ cordova build android # build debug for only Android + $ cordova build android --debug # build debug for only Android + $ cordova build android --release # build release for only Android + +If you are using the Android-specific shell tools in development, +there is a different approach. Once you generate the project, the +default app's source is available in the `assets/www` subdirectory. +Subsequent commands are available in its `cordova` subdirectory. + +The `build` command cleans project files and rebuilds the app. Here is +the syntax for both Mac and Windows. The first pair of examples +generate debugging information, and the second builds the apps for +release: + + $ /path/to/project/cordova/build --debug + C:\path\to\project\cordova\build.bat --debug + + $ /path/to/project/cordova/build --release + C:\path\to\project\cordova\build.bat --release + +## Deploy the app + +You can use the `cordova` CLI utility to deploy the +application to the emulator or the device from the command line: + + $ cordova emulate android #to deploy the app on a default android emulator + $ cordova run android --device #to deploy the app on a connected device + +Otherwise, use the alternate shell interface: + + $ /path/to/project/cordova/run --emulator + $ /path/to/project/cordova/run --device + +You can use __cordova run android --list__ to see all available targets and +__cordova run android --target=target_name__ to run application on a specific +device or emulator (for example, `cordova run android --target="Nexus4_emulator"`). + +You can also use __cordova run --help__ to see additional build and run +options. + +This pushes the app to the home screen and launches it: + + + +When you `run` the app, you also `build` it. You can append additional +`--debug`, `--release`, and `--nobuild` flags to control how it is +built, or even whether a rebuild is necessary: + + $ /path/to/project/cordova/run --emulator --nobuild + +## Other Commands + +The following generates a detailed log of the app as it runs: + + $ /path/to/project/cordova/log + C:\path\to\project\cordova\log.bat + +The following cleans the project files: + + $ /path/to/project/cordova/clean + C:\path\to\project\cordova\clean.bat + +## Open a New Project in the SDK + +Once android platform is added to your project, you can open it from +within [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio): + +1. Launch the __Android Studio__ application. + +1. Select __Import Project (Eclipse ADT, Gradle, etc)__. + +  + +1. Select location where android platform is stored (`your/project/platforms/android`). + +  + +1. For the `Gradle Sync` question you can simply answer __Yes__. + +You are all set now and can build and run the app directly from `Android Studio`. + + + +See [Android Studio Overview](http://developer.android.com/tools/studio/index.html) and +And [Building and Running from Android Studio](http://developer.android.com/tools/building/building-studio.html) for more details. + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/android/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/plugin.md b/www/docs/en/dev/guide/platforms/android/plugin.md new file mode 100644 index 0000000..e232ba6 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/android/plugin.md @@ -0,0 +1,361 @@ +--- +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. + +title: Android Plugins +--- + +# Android Plugins + +This section provides details for how to implement native plugin code +on the Android platform. Before reading this, see Application Plugins +for an overview of the plugin's structure and its common JavaScript +interface. This section continues to demonstrate the sample _echo_ +plugin that communicates from the Cordova webview to the native +platform and back. For another sample, see also the comments in +[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java). + +Android plugins are based on Cordova-Android, which consists of an +Android WebView with hooks attached to it. Plugins are represented as +class mappings in the `config.xml` file. A plugin consists of at +least one Java class that extends the `CordovaPlugin` class, +overriding one of its `execute` methods. As best practice, the plugin +should also handle `[pause](../../../cordova/events/events.pause.html)` and `[resume](../../../cordova/events/events.resume.html)` events, along with any message +passing between plugins. Plugins with long-running requests, +background activity such as media playback, listeners, or internal +state should implement the `onReset()` method as well. It executes +when the `WebView` navigates to a new page or refreshes, which reloads +the JavaScript. + +## Plugin Class Mapping + +The plugin's JavaScript interface uses the `cordova.exec` method as +follows: + + exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]); + +This marshals a request from the WebView to the Android native side, +effectively calling the `action` method on the `service` class, with +additional arguments passed in the `args` array. + +Whether you distribute a plugin as Java file or as a _jar_ file of its +own, the plugin must be specified in your Cordova-Android +application's `res/xml/config.xml` file. See Application Plugins for +more information on how to use the `plugin.xml` file to inject this +`feature` element: + + <feature name="<service_name>"> + <param name="android-package" value="<full_name_including_namespace>" /> + </feature> + +The service name matches the one used in the JavaScript `exec` call. +The value is the Java class's fully qualified namespace identifier. +Otherwise, the plugin may compile but still be unavailable to Cordova. + +## Plugin Initialization and Lifetime + +One instance of a plugin object is created for the life of each +`WebView`. Plugins are not instantiated until they are first +referenced by a call from JavaScript, unless `<param>` with an `onload` +`name` attribute is set to `"true"` in `config.xml`. E.g.: + + <feature name="Echo"> + <param name="android-package" value="<full_name_including_namespace>" /> + <param name="onload" value="true" /> + </feature> + +Plugins should use the `initialize` method for their start-up logic. + + @Override + public void initialize(CordovaInterface cordova, CordovaWebView webView) { + super.initialize(cordova, webView); + // your init code here + } + +## Writing an Android Java Plugin + +A JavaScript call fires off a plugin request to the native side, and +the corresponding Java plugin is mapped properly in the `config.xml` +file, but what does the final Android Java Plugin class look like? +Whatever is dispatched to the plugin with JavaScript's `exec` function +is passed into the plugin class's `execute` method. Most `execute` +implementations look like this: + + @Override + public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + this.beep(args.getLong(0)); + callbackContext.success(); + return true; + } + return false; // Returning false results in a "MethodNotFound" error. + } + +The JavaScript `exec` function's `action` parameter corresponds to a +private class method to dispatch with optional parameters. + +When catching exceptions and returning errors, it's important for the +sake of clarity that errors returned to JavaScript match Java's +exception names as much as possible. + +## Threading + +The plugin's JavaScript does _not_ run in the main thread of the +`WebView` interface; instead, it runs on the `WebCore` thread, as +does the `execute` method. If you need to interact with the user +interface, you should use the following variation: + + @Override + public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + final long duration = args.getLong(0); + cordova.getActivity().runOnUiThread(new Runnable() { + public void run() { + ... + callbackContext.success(); // Thread-safe. + } + }); + return true; + } + return false; + } + +Use the following if you do not need to run on the main interface's +thread, but do not want to block the `WebCore` thread either: + + @Override + public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + final long duration = args.getLong(0); + cordova.getThreadPool().execute(new Runnable() { + public void run() { + ... + callbackContext.success(); // Thread-safe. + } + }); + return true; + } + return false; + } + +## Adding Dependency Libraries + +If a plugin requires additional libraries to work, you can use +one of the following approaches to add them via `config.xml`. + +Option A. Via _Gradle_ reference, for example: + + <framework src="com.android.support:support-v4:+" /> + +This is a recommended approach as it allows multiple plugins +to refer to the same dependency library such as _gson_, +_android-support-v4_, _google-play-services_, etc and +_Gradle_ will resolve duplicate dependencies using its +[Dependency Management logic](https://docs.gradle.org/current/userguide/dependency_management.html). + +Option B. As _JAR_ files placed to some plugin's folder and +linked using `lib-file`, for example: + + <lib-file src="src/android/libs/gcm.jar"/> + +We recommend using this approach only if you are sure that +dependency jar is plugin specific and won't be used by +other plugins. Otherwise, there will be platform build issue. + +## Echo Android 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="android"> + <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."); + } + } + } + +The necessary imports at the top of the file extends the class from +`CordovaPlugin`, whose `execute()` method it overrides to receive +messages from `exec()`. The `execute()` method first tests the value +of `action`, for which in this case there is only one valid `echo` +value. Any other action returns `false` and results in an +`INVALID_ACTION` error, which translates to an error callback invoked +on the JavaScript side. + +Next, the method retrieves the echo string using the `args` object's +`getString` method, specifying the first parameter passed to the +method. After the value is passed to a private `echo` method, it is +parameter-checked to make sure it is not `null` or an empty string, in +which case `callbackContext.error()` invokes JavaScript's error +callback. If the various checks pass, the `callbackContext.success()` +passes the original `message` string back to JavaScript's success +callback as a parameter. + +## Android Integration + +Android features an `Intent` system that allows processes to +communicate with each other. Plugins have access to a +`CordovaInterface` object, which can access the Android `Activity` +that runs the application. This is the `Context` required to launch a +new Android `Intent`. The `CordovaInterface` allows plugins to start +an `Activity` for a result, and to set the callback plugin for when +the `Intent` returns to the application. + +As of Cordova 2.0, Plugins can no longer directly access the +`Context`, and the legacy `ctx` member is deprecated. All `ctx` +methods exist on the `Context`, so both `getContext()` and +`getActivity()` can return the required object. + +## Android Permissions + +Android permissions until recently have been handled at install-time instead +of runtime. These permissions are required to be declared on an application that uses +the permissions, and these permissions need to be added to the Android Manifest. This can be +accomplished by using the config.xml to inject these permissions in the AndroidManifest.xml file. +The example below uses the Contacts permission. + + <config-file target="AndroidManifest.xml" parent="/*"> + <uses-permission android:name="android.permission.READ_CONTACTS" /> + </config-file> + +## Android Permissions (Cordova-Android 5.0.x and greater) + +Android 6.0 "Marshmallow" introduced a new permissions model where +the user can turn on and off permissions as necessary. This means that +applications must handle these permission changes to be future-proof, which +was the focus of the Cordova-Android 5.0 release. + +The permissions that need to be handled at runtime can be found in the Android Developer +documentation [here](http://developer.android.com/guide/topics/security/permissions.html#perm-groups). + +As far as a plugin is concerned, the permission can be requested by calling the permission method, which signature is as follows: + + cordova.reqquestPermission(CordovaPlugin plugin, int requestCode, String permission); + +To cut down on verbosity, it's standard practice to assign this to a local static variable: + + public static final String READ = Manifest.permission.READ_CONTACTS; + +It is also standard practice to define the requestCode as follows: + + public static final int SEARCH_REQ_CODE = 0; + +Then, in the exec method, the permission should be checked: + + if(cordova.hasPermission(READ)) { + search(executeArgs); + } + else + { + getReadPermission(SEARCH_REQ_CODE); + } + +In this case, we just call requestPermission: + + protected void getReadPermission(int requestCode) + { + cordova.requestPermission(this, requestCode, READ); + } + +This will call the activity and cause a prompt to appear asking for the permission. Once the user has the permission, the result must be handled with the onRequestPermissionResult method, which +every plugin should override. An example of this can be found below: + + public void onRequestPermissionResult(int requestCode, String[] permissions, + int[] grantResults) throws JSONException + { + for(int r:grantResults) + { + if(r == PackageManager.PERMISSION_DENIED) + { + this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR)); + return; + } + } + switch(requestCode) + { + case SEARCH_REQ_CODE: + search(executeArgs); + break; + case SAVE_REQ_CODE: + save(executeArgs); + break; + case REMOVE_REQ_CODE: + remove(executeArgs); + break; + } + } + + +The switch statement above would return from the prompt and depending on the requestCode that was passed in, it would call the method. It should be noted that permission prompts may stack if the execution is not handled correctly, and that this should be avoided. + +In addition to asking for permission for a single permission, it is also possible to request permissions for an entire group by defining the permissions array, as what is done with the Geolocation plugin: + + String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION }; + +Then when requesting the permission, all that needs to be done is the following: + + cordova.requestPermissions(this, 0, permissions); + +This requests the permissions specified in the array. It's a good idea to provide a publicly accessible permissions array since this can be used by plugins that use your plugin as a +dependency, although this is not required. + +## Debugging Android Plugins + +Android debugging can be done with either Eclipse or Android Studio, although Android +studio is recommended. Since Cordova-Android is currently used as a library project, +and plugins are supported as source code, it is possible to debug the Java code inside +a Cordova application just like a native Android application. + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/android/tools.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/tools.md b/www/docs/en/dev/guide/platforms/android/tools.md new file mode 100644 index 0000000..119a863 --- /dev/null +++ b/www/docs/en/dev/guide/platforms/android/tools.md @@ -0,0 +1,224 @@ +--- +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. + +title: Android Shell Tool Guide +--- + +# Android Shell Tool Guide + +This guide shows how to use Cordova's set of platform-centered shell +tools to develop Android apps. This development path, discussed in the +[Overview](../../overview/index.html), may offer you a greater range of development options than +the cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html). +For example, you need to use shell tools when deploying a custom +Cordova WebView alongside native components. Before using either +development path, you must first configure the Android SDK environment +as described in the [Android Platform Guide](index.html). + +To enable shell tools for Android, download Cordova from +[cordova.apache.org](http://cordova.apache.org). The download contains +separate archives for each platform. Expand each you wish to target, +`android` in this case. The relevant tools are typically available in +the top-level `bin` directory, otherwise consult the __README__ file +for more detailed directions. + +These tools allow you to create, build, and run Android apps. For +information on the additional command-line interface that enables +plugin features across all platforms, see Using Plugman to Manage +Plugins. See Application Plugins for details on how to develop +plugins. + +## Create a Project + +Run the `create` command, specifying the existing path to the project, +the reverse-domain-style package identifier, and the app's display +name. Here is the syntax for both Mac/Linux and Windows: + + $ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectName + + C:\>\path\to\cordova-android\bin\create.bat \path\to\project com.example.project_name ProjectName + +## Build + +This cleans then builds a project. + +Debug, on Mac/Linux or Windows: + + $ /path/to/project/cordova/build --debug + + C:\>\path\to\project\cordova\build.bat --debug + +Release, on Mac/Linux or Windows: + + $ /path/to/project/cordova/build --release + + C:\>\path\to\project\cordova\build.bat --release + +## Run the App + +The `run` command accepts the following _optional_ parameters: + + * Target specification. This includes `--emulator`, `--device`, or `--target=<targetID>`. + + * Build specification. This includes `--debug`, `--release`, or `--nobuild`. + + $ /path/to/project/cordova/run [Target] [Build] + + C:\>\path\to\project\cordova\run.bat [Target] [Build] + +Make sure you create at least one Android Virtual Device, otherwise +you're prompted to do so with the `android` command. If more than one +AVD is available as a target, you're prompted to select one. By +default the `run` command detects a connected device, or a currently +running emulator if no device is found. + +## Signing the App + +You can review Android app signing requirements here: http://developer.android.com/tools/publishing/app-signing.html + +To sign an app, you need the following parameters: + + * Keystore (`--keystore`): Path to a binary file which can hold a set of keys. + + * Keystore password (`--storePassword`): Password to the keystore + + * Alias (`--alias`): The id specifying the private key used for singing. + + * Password (`--password`): Password for the private key specified. + + * Type of the keystore (`--keystoreType`): pkcs12, jks (Default: auto-detect based on file extension) + +These parameters can be specified using the command line arguments above to `build` or `run` scripts. + +Alternatively, you could specify them in a build configuration file (build.json) using (`--buildConfig`) argument. Here's a sample of a build configuration file: + + { + "android": { + "debug": { + "keystore": "..\android.keystore", + "storePassword": "android", + "alias": "mykey1", + "password" : "password", + "keystoreType": "" + }, + "release": { + "keystore": "..\android.keystore", + "storePassword": "", + "alias": "mykey2", + "password" : "password", + "keystoreType": "" + } + } + } + +For release signing, passwords can be excluded and the build system will issue a prompt asking for the password. + +There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence. This can be useful for specifying passwords on the command line. + +## Logging + + $ /path/to/project/cordova/log + + C:\>\path\to\project\cordova\log.bat + +## Cleaning + + $ /path/to/project/cordova/clean + + C:\>\path\to\project\cordova\clean.bat + +## Building with Gradle + +As of cordova-android@4.0.0, project build using [Gradle](http://www.gradle.org/). +For instructions on building with ANT, refer to older versions of documentation. + +### Gradle Properties + +These [properties](http://www.gradle.org/docs/current/userguide/tutorial_this_and_that.html) +can be set to customize the build: + + * **cdvBuildMultipleApks** (default: false) + + If this is set, then multiple APK files will be generated: One per native + platform supported by library projects (x86, ARM, etc). This can be important + if your project uses large native libraries, which can drastically increase + the size of the generated APK. + + If not set, then a single APK will be generated which can be used on all devices. + + * **cdvVersionCode** + + Overrides the versionCode set in `AndroidManifest.xml` + + * **cdvReleaseSigningPropertiesFile** (default: release-signing.properties) + + Path to a .properties file that contains signing information for release builds. + The file should look like: + ``` + storeFile=relative/path/to/keystore.p12 + storePassword=SECRET1 + storeType=pkcs12 + keyAlias=DebugSigningKey + keyPassword=SECRET2 + ``` + + `storePassword` and `keyPassword` are optional, and will be prompted for if omitted. + + * **cdvDebugSigningPropertiesFile** (default: debug-signing.properties) + + Same as cdvReleaseSigningPropertiesFile, but for debug builds. Useful when you need + to share a signing key with other developers. + + * **cdvMinSdkVersion** + + Overrides the value of `minSdkVersion` set in `AndroidManifest.xml`. Useful when + creating multiple APKs based on SDK version. + + * **cdvBuildToolsVersion** + + Override the automatically detected `android.buildToolsVersion` value. + + * **cdvCompileSdkVersion** + + Override the automatically detected `android.compileSdkVersion` value. + + +### Extending build.gradle + +If you need to customize `build.gradle`, rather than edit directly, you should create +a sibling file named `build-extras.gradle`. This file will be included by the main +`build.gradle` when present. Here's an example: + + # Example build-extras.gradle + # This file is included at the beginning of `build.gradle` + ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties' + # When set, this function allows code to run at the end of `build.gradle` + ext.postBuildExtras = { + android.buildTypes.debug.applicationIdSuffix = '.debug' + } + +Note that plugins can also include `build-extras.gradle` files via: + + <framework src="some.gradle" custom="true" type="gradleReference" /> + +### Example Build + + export ORG_GRADLE_PROJECT_cdvMinSdkVersion=14 + cordova build android -- --gradleArg=-PcdvBuildMultipleApks=true + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/platforms/android/upgrade.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/upgrade.md b/www/docs/en/dev/guide/platforms/android/upgrade.md new file mode 100644 index 0000000..33b2bee --- /dev/null +++ b/www/docs/en/dev/guide/platforms/android/upgrade.md @@ -0,0 +1,521 @@ +--- +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. + +title: Upgrading Android +--- + +# Upgrading Android + +This guide shows how to modify Android projects to upgrade from older versions of Cordova. +Most of these instructions apply to projects created with an older set +of command-line tools that precede the `cordova` CLI utility. See [The Command-Line Interface](../../cli/index.html) for information how to update the +version of the CLI. + +## Upgrading to 4.0.0 + +There are specific upgrade steps required to take advantage of the significant +changes in 4.0.0. First, the common upgrade steps are needed as below. + +For non-CLI projects, run: + + bin/update path/to/project + +For CLI projects: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update android` in your existing projects. + +### Upgrading the Whitelist +All whitelist functionality is now implemented via plugin. Without a plugin, +your app is no longer protected by a whitelist after upgrading to 4.0.0. Cordova +has two whitelist plugins, which provide different levels of protection. + +1. The `cordova-plugin-whitelist` plugin *(RECOMMENDED)* + * This plugin is highly recommended, as it is more secure and configurable + than the whitelist in previous versions + * See [cordova-plugin-whitelist](https://github.com/apache/cordova-plugin-whitelist) + for details on the configuration changes required + * Run: `cordova plugin add cordova-plugin-crosswalk-webview` + +2. The `cordova-plugin-legacy-whitelist` plugin + * This plugin provides the same whitelist behaviour as previous versions. See + [cordova-plugin-legacy-whitelist](https://github.com/apache/cordova-plugin-legacy-whitelist) + * No configuration changes are required, but it provides less protection than + the recommended plugin + * Run: `cordova plugin add cordova-plugin-legacy-whitelist` + +### Using the Crosswalk WebView +By default, your app will continue to use the system WebView provided by the +device. If you wish to use the Crosswalk WebView instead, simply add the +Crosswalk plugin: + + cordova plugin add cordova-plugin-crosswalk-webview + +Upon adding the plugin, your app will get the Crosswalk WebView installed and +configured correctly. + +### Upgrading to the Splashscreen Plugin +If your app makes use of a splash screen, that functionality has been moved to +a plugin. The configuration options for splash screens are unchanged. The only +upgrade step required is to add the plugin: + + cordova plugin add cordova-plugin-splashscreen + +## Upgrading to 3.7.1 from 3.6.0 + +For non-CLI projects, run: + + bin/update path/to/project + +For CLI projects: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update android` in your existing projects. + + +## Upgrading to 3.3.0 from 3.2.0 + +Follow the same instructions as for `3.2.0`. + +Starting with 3.3.0, the Cordova runtime is now compiled as an Android Library +instead of a Jar. This should have no effect for command-line usage, but IDE +users will need to import the newly added `MyProject-CordovaLib` project into +their workspace. + +## Upgrading to 3.2.0 from 3.1.0 + +For projects that were created with the cordova CLI: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update android` + +For projects not created with the cordova CLI, run: + + bin/update <project_path> + +**WARNING:** On Android 4.4 - Android 4.4.3, creating a file input element with type="file" will not open the file picker dialog. +This is a regression with Chromium on Android and the problem can be reproduced in the standalone Chrome browser on Android (see http://code.google.com/p/android/issues/detail?id=62220) The suggested workaround is to use the FileTransfer and File plugins for Android 4.4. You can listen for an onClick event from the input type="file" and then pop up a file picker UI. In order to tie the form data with the upload, you can use JavaScript to attach form values to the multi-part POST request that FileTransfer makes. + + +## Upgrading to 3.1.0 from 3.0.0 + +For projects that were created with the cordova CLI: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update android` + +For projects not created with the cordova CLI, run: + + bin/update <project_path> + +## Upgrade to the CLI (3.0.0) from 2.9.0 + +1. Create a new Apache Cordova 3.0.0 project using the cordova CLI, as + described in [The Command-Line Interface](../../cli/index.html). + +2. Add your platforms the cordova project, for example: `cordova + platform add android`. + +3. Copy the contents of your project's `www` directory to the `www` directory + at the root of the cordova project you just created. + +4. Copy any native assets from your old project into the appropriate + directories under `platforms/android`: this directory is where your + native cordova-android project exists. + +5. Use the cordova CLI tool to install any plugins you need. Note that + the CLI handles all core APIs as plugins, so they may need to be + added. Only 3.0.0 plugins are compatible with the CLI. + +## Upgrade to 3.0.0 from 2.9.0 + +1. Create a new Apache Cordova Android project. + +2. Copy the contents of the `www` directory to the new project. + +3. Copy any native Android assets from the `res` directory to the new project. + +4. Copy over any plugins you installed from the `src` subdirectories into the new project. + +5. Make sure to upgrade any deprecated `<plugin>` references from your old `config.xml` file to the new `<feature>` specification. + +6. Update any references to the `org.apache.cordova.api` package to be `org.apache.cordova`. + + __NOTE__: all core APIs have been removed and must be installed as plugins. Please see the [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html) Guide for details. + +## Upgrade to 2.9.0 from 2.8.0 + +1. Run `bin/update <project_path>`. + +## Upgrade to 2.8.0 from 2.7.0 + +1. Remove `cordova-2.7.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.8.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +<!-- SS Eclipse --> + +4. Copy the new `cordova.js` into your project. + +5. Update your HTML to use the new `cordova.js` file. + +6. Copy the `res/xml/config.xml` file to match `framework/res/xml/config.xml`. + +7. Update `framework/res/xml/config.xml` to have similar settings as it did previously. + +8. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.7.0 from 2.6.0 + +1. Remove `cordova-2.6.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.7.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.7.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.7.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Update `framework/res/xml/config.xml` to have similar settings as it did previously. + +8. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.6.0 from 2.5.0 + +1. Remove `cordova-2.5.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.6.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.6.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.6.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Update `framework/res/xml/config.xml` to have similar settings as it did previously. + +8. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +Run `bin/update <project>` with the project path listed in the Cordova Source directory. + +## Upgrade to 2.5.0 from 2.4.0 + +1. Remove `cordova-2.4.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.5.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.5.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.5.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Update `framework/res/xml/config.xml` to have similar settings as it did previously. + +8. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.4.0 from 2.3.0 + +1. Remove `cordova-2.3.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.4.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.4.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.4.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.3.0 from 2.2.0 + +1. Remove `cordova-2.2.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.3.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.3.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.3.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.2.0 from 2.1.0 + +1. Remove `cordova-2.1.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.2.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.2.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.2.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.1.0 from 2.0.0 + +1. Remove `cordova-2.0.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.1.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.1.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.1.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +7. Copy files from `bin/templates/cordova` to the project's `cordova` directory. + +## Upgrade to 2.0.0 from 1.9.0 + +1. Remove `cordova-1.9.0.jar` from the project's `libs` directory. + +2. Add `cordova-2.0.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-2.0.0.js` into your project. + +5. Update your HTML to use the new `cordova-2.0.0.js` file. + +6. Copy the `res/xml/config.xml` to match `framework/res/xml/config.xml`. + +In the 2.0.0 release, the `config.xml` file combines and replaces +`cordova.xml` and `plugins.xml`. The old files are deprecated, and +while they still work in 2.0.0, will stop working in a future release. + +## Upgrade to 1.9.0 from 1.8.1 + +1. Remove `cordova-1.8.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.9.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.9.0.js` into your project. + +5. Update your HTML to use the new `cordova-1.9.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +Due to the introduction of the `CordovaWebView` in the 1.9.0 release, +third-party plugins may not work. These plugins need to get a context +from the `CordovaInterface` using `getContext()` or `getActivity()`. +If you are not an experienced Android developer, please contact the +plugin maintainer and add this task to their bug tracker. + +## Upgrade to 1.8.0 from 1.8.0 + +1. Remove `cordova-1.8.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.8.1.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.8.1.js` into your project. + +5. Update your HTML to use the new `cordova-1.8.1.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.8.0 from 1.7.0 + +1. Remove `cordova-1.7.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.8.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.8.0.js` into your project. + +5. Update your HTML to use the new `cordova-1.8.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.8.0 from 1.7.0 + +1. Remove `cordova-1.7.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.8.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.8.0.js` into your project. + +5. Update your HTML to use the new `cordova-1.8.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.7.0 from 1.6.1 + +1. Remove `cordova-1.6.1.jar` from the project's `libs` directory. + +2. Add `cordova-1.7.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.7.0.js` into your project. + +5. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.6.1 from 1.6.0 + +1. Remove `cordova-1.6.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.6.1.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.6.1.js` into your project. + +5. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.6.0 from 1.5.0 + +1. Remove `cordova-1.5.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.6.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.6.0.js` into your project. + +5. Update your HTML to use the new `cordova-1.6.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +7. Replace `res/xml/phonegap.xml` with `res/xml/cordova.xml` to match `framework/res/xml/cordova.xml`. + +## Upgrade to 1.5.0 from 1.4.0 + +1. Remove `phonegap-1.4.0.jar` from the project's `libs` directory. + +2. Add `cordova-1.5.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `cordova-1.5.0.js` into your project. + +5. Update your HTML to use the new `cordova-1.5.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +7. Replace `res/xml/phonegap.xml` with `res/xml/cordova.xml` to match `framework/res/xml/cordova.xml`. + +## Upgrade to 1.4.0 from 1.3.0 + +1. Remove `phonegap-1.3.0.jar` from the project's `libs` directory. + +2. Add `phonegap-1.4.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `phonegap-1.4.0.js` into your project. + +5. Update your HTML to use the new `phonegap-1.4.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`. + +## Upgrade to 1.3.0 from 1.2.0 + +1. Remove `phonegap-1.2.0.jar` from the project's `libs` directory. + +2. Add `phonegap-1.3.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `phonegap-1.3.0.js` into your project. + +5. Update your HTML to use the new `phonegap-1.2.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`. + +## Upgrade to 1.2.0 from 1.1.0 + +1. Remove `phonegap-1.1.0.jar` from the project's `libs` directory. + +2. Add `phonegap-1.2.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `phonegap-1.2.0.js` into your project. + +5. Update your HTML to use the new `phonegap-1.2.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +7. Update `res/xml/phonegap.xml` to match `framework/res/xml/phonegap.xml`. + +## Upgrade to 1.1.0 from 1.0.0 + +1. Remove `phonegap-1.0.0.jar` from the project's `libs` directory. + +2. Add `phonegap-1.1.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `phonegap-1.1.0.js` into your project. + +5. Update your HTML to use the new `phonegap-1.1.0.js` file. + +6. Update `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + +## Upgrade to 1.0.0 from 0.9.6 + +1. Remove `phonegap-0.9.6.jar` from the project's `libs` directory. + +2. Add `phonegap-1.0.0.jar` to the project's `libs` directory. + +3. If you use Eclipse, please refresh your Eclipse project and do a clean. + +4. Copy the new `phonegap-1.0.0.js` into your project. + +5. Update your HTML to use the new `phonegap-1.0.0.js` file. + +6. Add the `res/xml/plugins.xml` to match `framework/res/xml/plugins.xml`. + --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
