Join CTO Moataz Soliman as he explores the potential impact poor performance can have on your bottom line. 👉 Register Today

ebook icon

App Development


Using Native Libraries in PhoneGap: A DIY Guide

Building mobile applications with web technologies greatly speeds up development, as well as the added benefit of shared code between platforms.

Sometimes, however, you need capabilities that aren't available in a web view, or maybe implementing will require too much work. That's when you break away from your cross-platform heaven back to native development.

Here we'll go through steps to take a native library and use it within our Cordova/PhoneGap application with the same JavaScript interface on both iOS and Android.

For this post, we'll pick our own library, on both platforms.

What we need is to build a Cordova plugin, with two platforms but with a unified JavaScript interface. The unified interface makes you interact with native code in either platforms accordingly.

1. Create your Cordova plugin

All we need to create a plugin is a directory with a plugin.xml file.

Here's a simple one we can start with:

2. Prepare your library

2.1 Android

With Cordova 4.0, we get first class support for Gradle. Luckily for us, the library is already available on Maven Central, so we don't need to download anything, but we need to specify that there's a Gradle dependency to be fetched.

Create a build.gradle file in your plugin directory, and add the dependencies in there:

In your plugin.xml file, inside the Android platform section, refer to the gradle file as a dependency, by adding this tag:

Depending on your library, you may need to define some AndroidManifest.xml entries. Since there's no application AndroidManifest.xml yet, you need to instruct Cordova about what entries to add.

We don't need to do that with Instabug since this is handled by Android's Gradle plugin Manifest Merger. If the library doesn't include the definitions, you can still add them inside your Android platform section like this:

This basically tells Cordova what entries to inject in the AndroidManifest.xml file, and under which XML node.

2.2 iOS

Download the library's framework and bundle files. Copy them into your plugin directory.

Go to your plugin.xml file, in the iOS platform section, add the files of the library. To add an iOS framework, use the framework tag, and to add a bundle file, use the resource-file tag. With our SDK, we have 2 files, we add them both:

We also need to add any system frameworks the library needs, for this, we use the framework tag as well. Refer to your library's documentation to know what frameworks are needed. Here's Instabug's list:

3. Write your native interface

Now you will need to write a native interface for that module. This module will connect your native code to Cordova, and this is the part where Cordova's native code is used.

3.1 Android

You will need to create a Java file. Let's call it "". We'll place it in our plugin directory.

This class should extend CordovaPlugin, which comes from Cordova. You can create a Java/Android project using your favorite IDE, but here, we'll just write the plain Java file. We are not looking to write many methods, anyway.

Now you will be looking into two methods. In the initialize() method, do whatever initialization you need to do.

In the execute() method, you'll need to implement all the actions that should be available in JavaScript.

Add new methods as you need. Take note that you're now sort of writing a public API for the library that should be identical on both platforms, unless you want your JavaScript code to be filled with platform-specific branches.

Depending on the library, you may need some workaround or configuration values to be supplied to the library.

Look, for example, at how we obtain an Application object to initialize Instabug. Also, how we extract the Android application token from the arguments parameter.

This parameter will be supplied from our JavaScript interface that we will write in a following step.

Here's what we ended up with in our "" file:

The feature name should be your Java class name.

3.2 iOS

In iOS, you need to do something similar. The major difference is the way you'll identify the actions. Instead of a parameter in the execute method, you should implement each action in its own method. So when in JavaScript you call the invoke() method, you should have an Objective-C invoke() method to be called.

You will need to define two files for the native code, let's call them "InstabugPhoneGap.m" and "InstabugPhoneGap.h". Put them in the same directory of the plugin right next to the .java file created earlier, where they would look weird.

Here's what we end up with:

Just like what we did with Android on the last section, add a config-file section inside the iOS platform to include our files:

The feature name should be your Objective-C class name.

4. Write your JavaScript binding API

You will now need to write the JavaScript API. This will be the code responsible for calling the native interfaces you have built in the previous step.

These methods are the ones that will be available to you in your Cordova project.

The key method here is cordova.exec, as that's your window to the native world. Basically, you give it what module to call, what action to take, and what parameters to send. If you have followed the steps earlier, you should end up with identical module names and identical action names on both native modules that you wrote. This is critical, because otherwise, a unified JavaScript API wouldn't work.

The implementation should be straightforward. You can define the methods any way you want, but we chose to separate the actions in four separate methods, each action with its own exec() call. We only need the parameters for the first method:

Let's save this as "instabug.js" in our plugin directory. We'll also need to declare it in our plugin.xml file to tell Cordova where to export it in the application:

5. Use your library

Here you're back to the comfort zone, as you'll just be using the JavaScript API you have developed in previous steps.

So, first, you want to add the plugin to your app. Go inside your application directory (Cordova project), and execute the following command (replace '../instabug-phonegap' with the actual plugin directory path):

The next step depends on how the library would be used. In our example, what we want is to initialize Instabug in onDeviceReady. There are many ways to do that in a Cordova project.

This now closes the loop of what we have been building so far.

  • The init call goes to instabug.js init method.
  • The init method in instabug.js calls cordova.exec.
  • cordova.exec method will delegate the call to a native method, depending on the platform.
  • Native code in Android or iOS will run that action accordingly.

For reference, here's the final plugin.xml we ended up with:






Start Your 14-Day Free Trial for Realtime Contextual Insights

In less than a minute, integrate the Instabug SDK for iOS, Android, React Native, Xamarin, Cordova, Flutter, and Unity mobile apps