Cordova > SDK integration

Initial setup

Batch Cordova is compatible with Cordova 6.4+, Cordova-iOS 3.0+ and Cordova-android 6.0+. The native OS versions supported are iOS 8+ (with Xcode 8+) and Android 4.0+.

The plugin works in cordova-based solutions, like Mobile Chrome Apps or Ionic. Other platforms supported by Cordova are not supported by Batch.

Setting up the SDK

First, download and extract the SDK in the place of your choice. Then go in your cordova project folder, and run cordova plugin add /path/to/batch-cordova-plugin.

Android specific notes

Batch Cordova will automatically bind itself on the app lifecycle events. You do not need to implement anything yourself.
Batch requires some permissions for all of its modules to work. For convinience, Batch Cordova will automatically add them to your app:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />

C2DM permissions for push will also be created automatically.

It will also add the latest version of two Google Play Services modules: ads and gcm. They are required respectively for Batch Ads and Batch Push.

If you want to override any of that, please edit batch-cordova-plugin/plugin.xml, look for the <config-file> lines. Be aware that you may break Batch functionality by doing so.

Your first start

Batch exposes a global batch object, which is your main entry point to any API that Batch provides.

The start function requires you to provide a configuration object. For example, a typical implementation in the www/js/init.js file will be:

var app = {
    onDeviceReady: function() {
        batch.setConfig({"androidAPIKey":"<YOUR_ANDROID_APIKEY>",
            "iOSAPIKey":"<YOUR_IOS_APIKEY>"});
        batch.start();
    }
};

YOUR_API_KEY is your Batch Dev or Live API key. You'll find the API keys needed to set up the SDK in ⚙ Settings → General:

  • Dev API key: Use it for development or testing purposes. This API key won't trigger stats computation. Please take care not to ship an app on a Store with this API key.
  • Live API key: Should be used in a production environment only and in the final version of your app on the Store.

Note that you should not use the same API key for iOS and Android. If you do not want to support one of these platforms, you are not required to provide an API Key for it.

Batch iOS API key must not be mistaken for the APNS environment Batch will output to the Xcode logs when starting. The environment depends on the app's provision, not on the Batch API Key used.

Do not try to use batch in initialize or bindEvents, batch will not be loaded yet. It is guaranteed to be loaded by cordova only in onDeviceReady.

Testing your integration

Congratulations on finishing the bulk of the integration!

If you want to validate your implementation before proceeding with the Push setup, you can locate the log that Batch posts in Chrome or Safari's remote debuggers in dev mode, depending on your platform:

Batch: Batch is running in dev mode (your API key is a dev one)
[Batch] Batch started with a DEV API key

Batch Sample Apps

If you want to see a proper integration of the Batch SDK and to test any of its functionalities, you can take a look at our sample apps.

Download the sample app on GitHub