http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.0.0/guide/platforms/amazonfireos/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/amazonfireos/index.md b/www/docs/en/6.0.0/guide/platforms/amazonfireos/index.md deleted file mode 100644 index 055f249..0000000 --- a/www/docs/en/6.0.0/guide/platforms/amazonfireos/index.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -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/21c8e8f0/www/docs/en/6.0.0/guide/platforms/amazonfireos/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/amazonfireos/plugin.md b/www/docs/en/6.0.0/guide/platforms/amazonfireos/plugin.md deleted file mode 100644 index d4fdac4..0000000 --- a/www/docs/en/6.0.0/guide/platforms/amazonfireos/plugin.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -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/21c8e8f0/www/docs/en/6.0.0/guide/platforms/amazonfireos/webview.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/amazonfireos/webview.md b/www/docs/en/6.0.0/guide/platforms/amazonfireos/webview.md deleted file mode 100644 index 4c018e5..0000000 --- a/www/docs/en/6.0.0/guide/platforms/amazonfireos/webview.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -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/21c8e8f0/www/docs/en/6.0.0/guide/platforms/android/config.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/android/config.md b/www/docs/en/6.0.0/guide/platforms/android/config.md deleted file mode 100644 index 6a120ad..0000000 --- a/www/docs/en/6.0.0/guide/platforms/android/config.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -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/21c8e8f0/www/docs/en/6.0.0/guide/platforms/android/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/android/index.md b/www/docs/en/6.0.0/guide/platforms/android/index.md deleted file mode 100644 index 4f97111..0000000 --- a/www/docs/en/6.0.0/guide/platforms/android/index.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -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/21c8e8f0/www/docs/en/6.0.0/guide/platforms/android/lifecycle.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/android/lifecycle.md b/www/docs/en/6.0.0/guide/platforms/android/lifecycle.md deleted file mode 100644 index 4c54359..0000000 --- a/www/docs/en/6.0.0/guide/platforms/android/lifecycle.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -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 Lifecycle Guide ---- - -# Android Lifecycle Guide - -## Cordova and Android - -Native Android apps typically consist of a series of [activities](http://developer.android.com/reference/android/app/Activity.html) that the user -interacts with. Activities can be thought of as the individual screens that make -up an application; different tasks in an app will often have their own activity. -Each activity has its own lifecycle that is maintained as the activity enters -and leaves the foreground of a user's device. - -In contrast, Cordova applications on the Android platform are executed within a -Webview that is embedded in a *single* Android activity. The lifecycle of this -activity is exposed to your application through the document events that are -fired. The events are not guaranteed to line up with Android's lifecycle, but -they can provide guidelines for saving and restoring your state. These events -roughly map to Android callbacks as follows: - -Cordova Event | Rough Android Equivalent | Meaning -----------------|---------------------------|----------------- -`deviceready` | `onCreate()` | Application is starting (not from background) -`pause` | `onPause()` | Application is moving to the background -`resume` | `onResume()` | Application is returning to the foreground - -Most other Cordova platforms have a similar concept of lifecycles and should -fire these same events when similar actions happen on a user's device. However, -Android presents some unique challenges that can sometimes show up thanks to the -native Activity lifecycle. - -## What makes Android different? - -In Android, the OS can choose to kill activities in the background in -order to free up resources if the device running the application is low on -memory. Unfortunately, when the activity holding your application is killed, -the Webview in which your application lives will be destroyed as well. Any state -that your application is maintaining will be lost in this case. When the user -navigates back to your application, the Activity and Webview will be -recreated by the OS, but state will not be automatically restored for your -Cordova app. For this reason, it is imperative that your application be aware of -the lifecycle events that are fired and maintain whatever state is appropriate -to make sure a user's context in your app is not lost when they leave the -application. - -## When can this happen? - -Your application is susceptible to being destroyed by the OS whenever it leaves -the sight of the user. There are two main situations in which this can occur. -The first and most obvious case is when the user presses the home button or -switches to another application. - -However, there is a second (and much more subtle) case that certain plugins can -introduce. As noted above, Cordova applications are usually confined to the -single activity that contains the Webview. However, there are instances in which -other activities may be launched by plugins and temporarily push the Cordova -activity to the background. These other Activities are typically launched in -order to perform a specific task using a native application installed on the -device. For example, the Apache camera plugin launches whatever camera activity -is natively installed on the device in order to take a photo. Reusing the -installed camera application in this way makes your application feel much more -like a native app when the user tries to take a photo. Unfortunately, when the -native Activity pushes your app to the background there is a chance the OS -will kill it. - -For a clearer understanding of this second case, let's walk through an example -using the camera plugin. Imagine you have an application that requires the user -to take a profile photo. The flow of events in the application when everything -goes as planned will look something like this: - -1. The user is interacting with your app and needs to take a picture -2. The camera plugin launches the native camera activity - * *The Cordova activity is pushed to the background (pause event is fired)* -3. The user takes a photo -4. The camera activity finishes - * *The Cordova activity is moved to the foreground (resume event is fired)* -5. The user is returned to your application where they left off - -However, this flow of events can be disrupted if a device is low on memory. If -the Activity is killed by the OS, the above sequence of events instead plays out -as follows: - -1. The user is interacting with your app and needs to take a picture -2. The camera plugin launches the native camera activity - * *The OS destroys the Cordova activity (pause event is fired)* -3. The user takes a photo -4. The camera activity finishes - * *The OS recreates the Cordova activity (deviceready and resume events are fired)* -5. The user is confused as to why they are suddenly back at your app's login screen - -In this instance, the OS killed the application in the background and the -application did not maintain its state as part of the lifecycle. When the user -returned to the app, the Webview was recreated and the app appeared to have -restarted from scratch (hence the user's confusion). This sequence of events is -equivalent to what happens when the home button is pressed or the user switches -applications. The key to preventing the above experience is subscribing to -events and properly maintaining state as part of the activity lifecycle. - -## Respecting the Lifecycle - -In the examples above, the javascript events that are fired are noted in -italics. These events are your opportunity to save and restore your -application's state. You should register callbacks in your application's -`bindEvents` function that respond to the lifecycle events by saving state. What -information you save and how you save it is left to your discretion, but you -should be sure to save enough information so that you can restore the user to -exactly where they left off when they return to your application. - -There is one additional factor in the example above that only applies in the -second-discussed situation (i.e. when a plugin launches an external activity). -Not only was the state of the application lost when the user finished taking a -photo, but so was the photo that the user took. Normally, that photo would be -delivered to your application through the callback that was registered with the -camera plugin. However, when the Webview was destroyed that callback was lost -forever. Luckily, cordova-android 5.1.0 and above provide a means for getting -the result of that plugin call when your application resumes. - -## Retrieving plugin callback results (cordova-android 5.1.0+) - -When the OS destroys the Cordova activity that was pushed into the background -by a plugin, any pending callbacks are lost as well. This means that if you -passed a callback to the plugin that launched the new activity (e.g. the camera -plugin), that callback will NOT be fired when the application is recreated. -However, starting in cordova-android **5.1.0**, the `resume` event's payload will -contain any pending plugin results from the plugin request that launched the -external activity made prior to the activity being destroyed. - -The payload for the `resume` event adheres to the following format: - -``` -{ - action: "resume", - pendingResult: { - pluginServiceName: string, - pluginStatus: string, - result: any - } -} -``` - -The fields of that payload are defined as follows: - -* `pluginServiceName`: The name of the plugin returning the result (e.g. "Camera"). This can be found in the `<name>` tag of a plugin's plugin.xml file -* `pluginStatus`: The status of the plugin call (see below) -* `result`: Whatever the result of the plugin call is - -The possible values for `pluginStatus` in the `pendingResult` field include the following: -* `"OK"` - The plugin call was successful -* `"No Result"` - The plugin call ended with no result -* `"Error"` - The plugin call resulted in some general error -* Other miscellaneous errors - * `"Class not found"` - * `"Illegal access"` - * `"Instantiation error"` - * `"Malformed url"` - * `"IO error"` - * `"Invalid action"` - * `"JSON error"` - -Please note that it is up to the plugin to decide what is contained in the -`result` field and the meaning of the `pluginStatus` that is returned. Reference -the API of the plugin you are using to see what you should expect those fields -to contain and how to use their values. - -### Example - -Below is a brief example application that uses the `resume` and `pause` events -to manage state. It uses the Apache camera plugin as an example of how to -retrieve the results of a plugin call from the `resume` event payload. The -portion of the code dealing with the `resume`'s `event.pendingResult` object -requires cordova-android **5.1.0+** - -```javascript -// This state represents the state of our application and will be saved and -// restored by onResume() and onPause() -var appState = { - takingPicture: true, - imageUri: "" -}; - -var APP_STORAGE_KEY = "exampleAppState"; - -var app = { - initialize: function() { - this.bindEvents(); - }, - bindEvents: function() { - // Here we register our callbacks for the lifecycle events we care about - document.addEventListener('deviceready', this.onDeviceReady, false); - document.addEventListener('pause', this.onPause, false); - document.addEventListener('resume', this.onResume, false); - }, - onDeviceReady: function() { - document.getElementById("take-picture-button").addEventListener("click", function() { - // Because the camera plugin method launches an external Activity, - // there is a chance that our application will be killed before the - // success or failure callbacks are called. See onPause() and - // onResume() where we save and restore our state to handle this case - appState.takingPicture = true; - - navigator.camera.getPicture(cameraSuccessCallback, cameraFailureCallback, - { - sourceType: Camera.PictureSourceType.CAMERA, - destinationType: Camera.DestinationType.FILE_URI, - targetWidth: 250, - targetHeight: 250 - } - ); - }); - }, - onPause: function() { - // Here, we check to see if we are in the middle of taking a picture. If - // so, we want to save our state so that we can properly retrieve the - // plugin result in onResume(). We also save if we have already fetched - // an image URI - if(appState.takingPicture || appState.imageUri) { - window.localStorage.setItem(APP_STORAGE_KEY, JSON.stringify(appState)); - } - }, - onResume: function(event) { - // Here we check for stored state and restore it if necessary. In your - // application, it's up to you to keep track of where any pending plugin - // results are coming from (i.e. what part of your code made the call) - // and what arguments you provided to the plugin if relevant - var storedState = window.localStorage.getItem(APP_STORAGE_KEY); - - if(storedState) { - appState = JSON.parse(storedState); - } - - // Check to see if we need to restore an image we took - if(!appState.takingPicture && appState.imageUri) { - document.getElementById("get-picture-result").src = appState.imageUri; - } - // Now we can check if there is a plugin result in the event object. - // This requires cordova-android 5.1.0+ - else if(appState.takingPicture && event.pendingResult) { - // Figure out whether or not the plugin call was successful and call - // the relevant callback. For the camera plugin, "OK" means a - // successful result and all other statuses mean error - if(event.pendingResult.pluginStatus === "OK") { - // The camera plugin places the same result in the resume object - // as it passes to the success callback passed to getPicture(), - // thus we can pass it to the same callback. Other plugins may - // return something else. Consult the documentation for - // whatever plugin you are using to learn how to interpret the - // result field - cameraSuccessCallback(event.pendingResult.result); - } else { - cameraFailureCallback(event.pendingResult.result); - } - } - } -} - -// Here are the callbacks we pass to getPicture() -function cameraSuccessCallback(imageUri) { - appState.takingPicture = false; - appState.imageUri = imageUri; - document.getElementById("get-picture-result").src = imageUri; -} - -function cameraFailureCallback(error) { - appState.takingPicture = false; - console.log(error); -} - -app.initialize(); -``` - -The corresponding html: - -```html -<!DOCTYPE html> - -<html> - <head> - <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"> - <meta name="format-detection" content="telephone=no"> - <meta name="msapplication-tap-highlight" content="no"> - <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width"> - <link rel="stylesheet" type="text/css" href="css/index.css"> - <title>Cordova Android Lifecycle Example</title> - </head> - <body> - <div class="app"> - <div> - <img id="get-picture-result" /> - </div> - <Button id="take-picture-button">Take Picture</button> - </div> - <script type="text/javascript" src="cordova.js"></script> - <script type="text/javascript" src="js/index.js"></script> - </body> -</html> -``` - -## Testing the Activity Lifecycle - -Android provides a developer setting for testing Activity destruction on low -memory. Enable the "Don't keep activities" setting in the Developer Options menu -on your device or emulator to simulate low memory scenarios. You should always -do some amount of testing with this setting enabled to make sure that your -application is properly maintaining state. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.0.0/guide/platforms/android/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/android/plugin.md b/www/docs/en/6.0.0/guide/platforms/android/plugin.md deleted file mode 100644 index 9cb25db..0000000 --- a/www/docs/en/6.0.0/guide/platforms/android/plugin.md +++ /dev/null @@ -1,464 +0,0 @@ ---- -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.requestPermission(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. - -## Launching Other Activities - -There are special considerations to be made if your plugin launches an Activity -that pushes the Cordova Activity to the background. The Android OS will destroy -Activities in the background if the device is running low on memory. In that -case, the CordovaPlugin instance will be destroyed as well. If your plugin is -waiting on a result from the Activity it launched, a new instance of your plugin -will be created when the Cordova Activity is brought back to the foreground and -the result is obtained. However, state for the plugin will not be automatically -saved or restored and the CallbackContext for the plugin will be lost. There are -two methods that your CordovaPlugin may implement to handle this situation: - -```java -/** - * Called when the Activity is being destroyed (e.g. if a plugin calls out to an - * external Activity and the OS kills the CordovaActivity in the background). - * The plugin should save its state in this method only if it is awaiting the - * result of an external Activity and needs to preserve some information so as - * to handle that result; onRestoreStateForActivityResult() will only be called - * if the plugin is the recipient of an Activity result - * - * @return Bundle containing the state of the plugin or null if state does not - * need to be saved - */ -public Bundle onSaveInstanceState() {} - -/** - * Called when a plugin is the recipient of an Activity result after the - * CordovaActivity has been destroyed. The Bundle will be the same as the one - * the plugin returned in onSaveInstanceState() - * - * @param state Bundle containing the state of the plugin - * @param callbackContext Replacement Context to return the plugin result to - */ -public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {} -``` - -It is important to note that the above methods should only be used if your -plugin launches an Activity for a result and should only restore the state -necessary to handle that Activity result. The state of the plugin will *NOT* be -restored except in the case where an Activity result is obtained that your -plugin requested using the CordovaInterface's `startActivityForResult()` method -and the Cordova Activity was destroyed by the OS while in the background. - -As part of `onRestoreStateForActivityResult()`, your plugin will be passed a -replacement CallbackContext. It is important to realize that this -CallbackContext *IS NOT* the same one that was destroyed with the Activity. The -original callback is lost, and will not be fired in the javascript application. -Instead, this replacement CallbackContext will return the result as part of the -`resume` event that is fired when the application resumes. The payload of the -`resume` event follows this structure: - -``` -{ - action: "resume", - pendingResult: { - pluginServiceName: string, - pluginStatus: string, - result: any - } -} -``` - -* `pluginServiceName` will match the `name` attribute from your plugin.xml -* `pluginStatus` will be a String describing the status of the PluginResult - passed to the CallbackContext. See PluginResult.java for the String values - that correspond to plugin statuses -* `result` will be whatever result the plugin passes to the CallbackContext - (e.g. a String, a number, a JSON object, etc.) - -This resume payload will be passed to any callbacks that the javascript -application has registered for the `resume` event. This means that the result is -going *directly* to the Cordova application; your plugin will not have a chance -to process the result with javascript before the application receives it. -Consequently, you should strive to make the result returned by the native code -as complete as possible and not rely on any javascript callbacks when launching -activities. - -Be sure to communicate how the Cordova application should interpret the result -they receive in the `resume` event. It is up to the Cordova application to -maintain their own state and remember what requests they made and what arguments -they provided if necessary. However, you should still clearly communicate the -meaning of `pluginStatus` values and what sort of data is being returned in the -`result` field as part of your plugin's API. - -The complete sequence of events for launching an Activity is as follows - -1. The Cordova application makes a call to your plugin -2. Your plugin launches an Activity for a result -3. The Android OS destroys the Cordova Activity and your plugin instance - * *`onSaveInstanceState()` is called* -4. The user interacts with your Activity and the Activity finishes -5. The Cordova Activity is recreated and the Activity result is received - * *`onRestoreStateForActivityResult()` is called* -6. `onActivityResult()` is called and your plugin passes a result to the new - CallbackContext -7. The `resume` event is fired and received by the Cordova application - -Android provides a developer setting for debugging Activity destruction on low -memory. Enable the "Don't keep activities" setting in the Developer Options menu -on your device or emulator to simulate low memory scenarios. If your plugin -launches external activities, you should always do some testing with this -setting enabled to ensure that you are properly handling low memory scenarios. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/21c8e8f0/www/docs/en/6.0.0/guide/platforms/android/tools.md ---------------------------------------------------------------------- diff --git a/www/docs/en/6.0.0/guide/platforms/android/tools.md b/www/docs/en/6.0.0/guide/platforms/android/tools.md deleted file mode 100644 index 119a863..0000000 --- a/www/docs/en/6.0.0/guide/platforms/android/tools.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -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 - --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
