Integrating 3rd party Cordova plug-ins in Worklight/MobileFirst 6.x - 7.0

When developing mobile applications you may come across situations where you will need to incorporate functionality that is not readily available to implement in Hybrid applications. This can be solved by integrating 3rd party Cordova plug-ins in your application. However, there are some hurdles standing in the way to achieving this integration:

  • Worklight/MobileFirst releases v6.x -> v7.0 do not support Cordova Plugman, so you cannot simply "install" a plug-in.
  • The current feature implementation for Cordova plug-ins in the product does not allow adding existing 3rd party Cordova plug-ins (you can, however, create your own).

Fortunately there are several solutions:

  1. Upgrade to IBM MobileFirst Platform Foundation 7.1, now providing the ability to create Cordova applications (iOS and Android), where MobileFirst SDK is integrated as a plug-in like any, thus also enabling you to integrate with any 3rd party Cordova plug-in as you would in any standard Cordova application
  2. Follow the instructions provided below for a workaround (by no means an official response or fix) to the presented difficulty

End-to-end examples

You can find end-to-end integration examples in the following links.
These examples miss one step that is explained below - using Ant tasks to re-introduce required Cordova plug-in references.

Integration instructions

As can be seen in the examples from StackOverflow there are two additional important steps required:

  1. The plug-in's JavaScript implementation must be surrounded with the following:
    • At the top add:
      cordova.define("nl.x-services.plugins.replace-with-JS-filename", function(require, exports, module) {
    • At the bottom add:

    Make sure to replace the placeholder text "replace-with-js-filename" with the correct filename value.

  2. The plug-in definition needs to be added to the cordova_plugins.js file. This is where we're hit with a problem; this file is considered a framework file and because of that, it gets auto-regenerated with each build performed in Worklight/MobileFirst Studio, and so any change that we do in it will be lost, essentially breaking the plug-in. Find the cordova_plugins.js file in the your-environment\native\www\default\worklight folder, and:
    • Add a Cordova plug-in definition
          "file": "../js/replace-with-JS-filename.js",
          "id": "nl.x-services.plugins.replace-with-JS-filename",
          "clobbers": [

      The plug-in typically resides in the common\js folder, hence ../js/.

The next step is to create an Ant task that will copy back our changes after the Studio build finished:

  1. Copy the edited cordova_plugin.js to a location of your choosing
  2. In your project, create a new build.xml file
    • For auto-complete assistance, in Eclipse Preferences > General > Editors > File Associations add build.xml as a File type and Ant Editor as the Associated editor.
  3. Copy and paste the following into the file:
    <project name="FixCordovaPlugin" basedir=".">
        <target name="CopyFile">
        	<echo message="Copying cordova_plugin.js back to Project" />
            <copy file="path-to/cordova_plugins.js" overwrite="true" tofile="path-to/project-name/apps/app-name/environment-name/native/www/default/worklight/cordova_plugins.js"/>

    Replace the following with the corresponding value: path-to, project-name, app-name, environment-name.

  4. Highlight the project folder and select Project > Properties > Builders
  5. Add a new Builder by clicking on New...> Ant builder
    • In the Main tab: Provide a name and the path to the build.xml file
    • In the Targets tab, for Auto Build, click Set Targets... and select the CopyFile task.
  6. Make sure that the Builder is the last in the list

Now when running a build in Worklight/MobileFirst Studio, while the build phase will initially overwrite the changes made to cordova_plugins.js, the Ant task will replace the generated file with a backed-up file.

Final Notes

This is only one Ant task implementation of many possible ones, and should direct you to the right, custom, solution best suited for your needs.

if you're using the encryptWebResources option, though, you may be out of luck as the Ant task takes place After the build has already placed all app resources in an encrypted .zip...

The best solution of them all, is to create a Cordova application in MobileFirst Platform Foundation 7.1.

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on May 01, 2016