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 +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.

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 @@ -188,93 +181,68 @@ background activity such as media playba 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 +

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, +

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 +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 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.
+

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

- +

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" />
+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.
-
+

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

- +

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 +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)) {
+        if ("beep".equals(action)) {
             this.beep(args.getLong(0));
             callbackContext.success();
             return true;
         }
-        return false;  // Returning false results in a "MethodNotFound" error.
+        return false;  // Returning false results in a "MethodNotFound" error.
     }
-

- -

The JavaScript exec function's action parameter corresponds to a +

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 +

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 +

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)) {
+        if ("beep".equals(action)) {
             final long duration = args.getLong(0);
             cordova.getActivity().runOnUiThread(new Runnable() {
                 public void run() {
@@ -286,14 +254,11 @@ interface, you should use the following
         }
         return false;
     }
-

- -

Use the following if you do not need to run on the main interface's +

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)) {
+        if ("beep".equals(action)) {
             final long duration = args.getLong(0);
             cordova.getThreadPool().execute(new Runnable() {
                 public void run() {
@@ -305,26 +270,19 @@ thread, but do not want to block the


-
-Echo Android Plugin Example
-
-

To match the JavaScript interface's echo feature described in +

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"/>
+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
+

Then add the following to the src/org/apache/cordova/plugin/Echo.java file:

    package org.apache.cordova.plugin;
 
     import org.apache.cordova.CordovaPlugin;
@@ -341,7 +299,7 @@ specification to the local platform's

-
-

The necessary imports at the top of the file extends the class from +

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 +

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 +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 +passes the original message string back to JavaScript's success callback as a parameter.

- -

Android Integration

- +

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 @@ -385,16 +338,11 @@ that runs the application. This is the 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.

- -

-Debugging Android Plugins -

- +

Debugging Android Plugins

Eclipse allows you to debug plugins as Java source included in the project. Only the latest version of the Android Developer Tools allows you to attach source code to JAR dependencies, so this Modified: cordova/site/public/docs/en/edge/guide_platforms_android_tools.md.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/edge/guide_platforms_android_tools.md.html?rev=1673862&r1=1673861&r2=1673862&view=diff ============================================================================== --- cordova/site/public/docs/en/edge/guide_platforms_android_tools.md.html (original) +++ cordova/site/public/docs/en/edge/guide_platforms_android_tools.md.html Wed Apr 15 16:43:43 2015 @@ -1,4 +1,3 @@ - +--> + + + - - + Apache Cordova API Documentation @@ -40,7 +41,7 @@ - + @@ -104,7 +105,9 @@ - + + + @@ -121,19 +124,13 @@ - + +

Android Shell Tool Guide

- +

@@ -166,8 +163,7 @@

Android Shell Tool Guide

- -

This guide shows how to use Cordova's set of platform-centered shell +

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, may offer you a greater range of development options than the cross-platform CLI tool described in The Command-Line Interface. @@ -175,200 +171,149 @@ For example, you need to use shell tools 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.

To enable shell tools for Android, download Cordova from 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 +plugin features across all platforms, see Using Plugman to Manage Plugins. See Application Plugins for details on how to develop plugins.

- -

Create a Project

- +

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 +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

- +

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:

- +

Release, on Mac/Linux or Windows:

    $ /path/to/project/cordova/build --release
 
     C:\>\path\to\project\cordova\build.bat --release
-

- -

Run the App

- +

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.
- +
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 +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.

- -

Logging

- +

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 comamnd 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

- +

Cleaning

    $ /path/to/project/cordova/clean
 
     C:\>\path\to\project\cordova\clean.bat
-

- -

Manual Use of Ant

- -

If you wish to call Ant directly from the command line such as -ant debug install, you need to specify additional parameters to the ant -command:

- -

    ant debug install -Dout.dir=ant-build -Dgen.absolute.dir=ant-gen
-

- -

This is because the directories used by Cordova's Ant scripts are different -than the default. This is done to avoid conflicts when Ant is run from the -command line versus inside Eclipse/ADT.

- -

These additional parameters are automatically added for you when using -the cordova/build and cordova/run scripts described above. For this -reason it is recommended to use the cordova/build and cordova/run scripts -instead of calling Ant directly from the command line.

- -

Building with Gradle (Experimental!)

- -

Cordova for Android now supports building with -Gradle. This is optional in Cordova 3.x, but will be -enabled by default in the future, probably with Cordova 4.0. The build system -is controlled with environment variables, which can be set for the shell, or -specified on the command line alongside the cordova build command.

- -

Please note that the Gradle build rules are still in development, and will -likely be subject to large changes before Gradle becomes the default build -system. Developers are encouraged to try it, and experiment with it, but if you -base your own production build system on top of it, you will probably -experience several breaking changes over the next few releases, before it -stabilizes.

- -

Relevant Environment Variables

- +

Building with Gradle

As of cordova-android@4.0.0, project build using Gradle. +For instructions on building with ANT, refer to older versions of documentation.

Gradle Properties

These properties +can be set to customize the build:

-
ANDROID_BUILD
- -
This variable controls which build system is used to build the project. In -can take either of the values ant or gradle.
- -
If not set, it currently defaults to ant, but this is expected to change.
-
-
BUILD_MULTIPLE_APKS
- +
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.
-
BUILD_MULTIPLE_APKS
- -
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.
-
-
ANDROID_VERSION_CODE
- +
cdvVersionCode

Overrides the versionCode set in AndroidManifest.xml
-
RELEASE_SIGNING_PROPERTIES_FILE
- +
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 +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.
+
```
storePassword and keyPassword are optional, and will be prompted for if omitted.

- -

Other Environment Variables (you don't normally need to set these)

- -

-
ANDROID_HOME
- -
This should be set to the directory containing the Android SDK.
+
cdvDebugSigningPropertiesFile (default: debug-signing.properties)
+
Same as cdvReleaseSigningPropertiesFile, but for debug builds. Useful when you need +to share a signing key with other developers.
-
JAVA_HOME
- -
On some machines, this will need to be set so that Gradle can find the Java -compiler. On OSX, the value for this variable can be found by running -/usr/libexec/java_home
+
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

- +

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.

- -

Example Build

- -

    ANDROID_BUILD=gradle cordova build android
+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-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org