Creating a Cordova Android Plugin in Kotlin
Recently only Java was the available programming language for Cordova Android plugins. Since Cordova Android 9.0.0, Kotlin support was introduced and could be used easily without hacking the platform core with hook scripts.
Developers can continue to program in Java, if preferred, or use Kotlin. In fact, Kotlin is designed with Java interoperability. Developers can write Java and Kotlin in tandem.
This article will show how to configure the plugin to support Kotlin and use the Apache Cordova’s Echo plugin, from their documentation, as the example. The example code is in Java, but I will provide a Kotlin equivalent. This guide will not going into details of Kotlin or how to write Kotlin code.
First, let’s create a workspace to store our plugin source code and the test app for testing the new plugin.
As a side note, the terminal commands provided in this article will work on a macOS and Linux environment. If you’re on a Windows machine, you may need to adjust to make valid Windows command. Alternatively, you may use Linux Subsystem for Windows or an alternative terminal (Cygwin) that supports Linux commands.
Create the Workspace:
mkdir cordova-workspace
cd cordova-workspace
Create the Plugin Directory & NPM Package
mkdir cordova-plugin-echo
cd cordova-plugin-echo
npm init -y
To minimize the number of steps in this guide, I am passing in the -y
argument to accept all default values. You can enter manual values, but this guide is not covering npm.
Note: The default package’s
name
property will be the directory name. This package name is the plugin name, that used in thecordova plugin
command. It must be unique and does not already exist in the npm registry for a successful publish.
Update package.json for Cordova Plugin
From this step, I will be using Visual Studio Code text editor for creating and editing plugin files. You may use your favorite text editor of choice. In the text editor, make sure to open the cordova-plugin-echo
directory.
Copy the package.json
snippet below and replace everything that was created by the npm init
command.
For a short overview of the changes:
- Updated the
description
property. It is not required for the success of the guide. It is useful for the npm registry search function. - Added the
keywords
property with values ofecosystem:cordova
andcordova-android
. It is not required for the success of the guide but important for filter the npm registry for cordova plugins. - Added the
engines
property withcordovaDependencies
. It defines the plugin requirements necessary for installing the plugin. The CLI version maybe lowered to 10.x, but Cordova-Android 10.1.1 or greater is preferred. - Added the
cordova
property that declares basic plugin information and supported platforms.
Create Cordova Plugin Base Files
Create plugin.xml
In the plugin’s root directory, create a file named plugin.xml
.
The plugin.xml
file is were plugin developers define settings, resource files and third-party libraries necessary for a successful integration to the app project. It also contains some identical information from package.json
file for backward compatibility support with older Cordova CLIs.
Below is the basic boiler plate content for this file.
Note: In the aboveX ML, there is a
platform
node with thename
attribute of Android. We will return to this node to add platform-specific settings and resource files later in this guide.
Create Android Plugin Source Code
In the plugin’s root directory, create the following directory structure:
src/android/org/apache/cordova/plugin/echo
Visual Studio Code Tip: You can right-click on the File Explore Tree, select
New File
, and paste the entire directory structure above. It will recursively create each directory for you.Terminal Command (Linux/macOS):
mkdir -p src/android/org/apache/cordova/plugin/echo
In the new echo
directory, create a new file named Echo.kt
and add the following code snippet.
For general information about the source code above, please read the Apache Cordova documentation. Keep in mind that the source in the documentation is in Java, but the explanation should still apply.
Update plugin.xml
Now that we have our source code added to our plugin, we need to update the plugin.xml
file to ensure that the source file is copied into the correct location of the app when installed.
If you have created a Cordova Android plugin before, you will notice nothing is unique to above XML snippet except that the source file extension has changed from java
to kt
.
Now we will enable Kotlin support, for the app developers, for a successful build.
To enable Kotlin support, add the GradlePluginKotlinEnabled
preferences flag to the Android’s config-file
block. This flag is the primary component necessary to allow the build process to compile Kotlin code, and is the newest flag introduced in Cordova-Android 9.0.0.
See below on how I have added the preference flag to the exisiting code block.
Testing
To quickly test the plugin, let’s create a simple Cordova-base project in the cordova-workspace
directory, add the Cordova-Android platform, install our new plugin, and build the app.
cordova create testProject com.foobar.testProject testProject
cd testProject
cordova platform add android@10.1.1
cordova plugin add ../cordova-plugin-echo
cordova build android
If all steps were successful, a successful build message should display in the terminal.
Note: During the
cordova plugin add
command, we passed in a relative path to thecordova-plugin-echo
plugin directory, which should be adjacent to the Cordova app project directory.
Now that a successful build is confirmed, we can go the extra mile and actually open the app project with Android Studio and launch the app in the emulator.
The correct directory to open with Android Studio iscordova-workspace/testProject/platforms/android
Within Android Studio, click on the run button. Simple as that!
Once the emulator launches, the app should open and display “Device is Ready”.
If we open the Google Chrome Device Inspector (chrome://inspect/devices#devices) and access the DevTools of the running application, we can verify that the following JavaScript (JS) code will execute our plugin source code.
After executing the above code, we should see “success: Test Message” printed in the console.
This test proves that the front-end layer communicates with the native layer, and the native layer returns a successful response. This sample plugin gives an example on how communication is created between layers.
Generally, you would create a JS wrapper and clobber it onto the window
object to simplify the code that app developers would use, but this guide does not covered this process. You can find more about this and other resources on the Apache Cordova documentation.
I hope this guide has gives you a good starting point with plugin development in Cordova Android with Kotlin. We can’t wait to see your awesome plugins in the npm registry.