SDK integration

Note: This documentation has been archived and should only be used for integrating Batch Cordova 2.x.

Batch Cordova is compatible with Cordova 8.0.0+, Cordova-iOS 4.5.0+ and Cordova-android 7.0.0+. The native OS versions supported are iOS 8+ (with Xcode 9+) and Android 4.0+.

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

Setting up the SDK

Use the cordova CLI to add the plugin:

cordova plugin add com.batch.cordova

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.

Setting up push notifications

Android Setup

On Android, Batch makes full use of Firebase Cloud Messaging.

In order to enable notifications, you will have to get the google-services.json file for your project. If you don't have this file yet, please follow the "Manually add Firebase" part of this documentation until you get it.

Once you've located the google-services.json file, simply add it to your project root.
Your directory tree should look like that:

- myapp
  | [...]
  | platforms/
  | plugins/
  | www/
  | config.xml
  | google-services.json    <--- This is where the file goes
  \ package.json

With that done, notifications will automatically work.

HIGHLY RECOMMENDED


Follow the [Customizing Batch notifications](/cordova/advanced/customizing-notifications#setting-up-custom-push-icons) guide to display your notification icon correctly on Android and manage your iOS/Android notification display.

iOS Setup

On iOS, you need to call batch.push.registerForRemoteNotifications() every time your application is started. You can, however, delay the very first call to another place in your app, so that the notification request popup is shown at a later date.

var app = {
    onDeviceReady: function() {
        batch.setConfig({"androidAPIKey":"<YOUR ANDROID APIKEY>",
            "iOSAPIKey":"<YOUR IOS APIKEY>"});
        batch.start();
        batch.push.registerForRemoteNotifications();
    }
};

Many Batch calls can be chained, as shown in that example.

Your first notification

1. Obtaining your device token

You can find your device's token using the debug tool or locating the token Batch posts to the logs. Be sure to launch the app on your device linked to your computer.

Batch's logs are displayed in the logcat/Xcode console, but they are also forwarded.

Recent Android versions should show logs that happened before you opened Chrome's debugger, but older android versions and iOS do not, so you might miss the push token here. In that case, you need to take a look in the device logs (Window -> Devices for Xcode, adb logcat for android).

The line you are looking for within the logcat/console is:

  • Android
  • iOS
Batch.Push: Registration id: X

//Where X represents the Batch Push token for your device.

2. Sending a test push

Go to ⚙ Settings → Push settings, paste your device's token and click on Save. On iOS, make sure you chose the right environment.

Then, all you have to do is to click on the "Send" button. If you sucessfuly set up the SDK, you will receive a notification on your device.

Test push iOS

Troubleshooting
If you're having trouble sending test notifications, you can check our troubleshooting documentation:

What's next

Congratulations on finishing the integration of Batch Push!

Here are a couple of extra steps you can take before releasing your app:

  • Live API key: Ensure you don't use Batch's DEV API key in the build you will upload to the AppStore / Play Store.
  • Small icon / Accent color: On Android, make sure the small icon you are using is opaque white. We also recommend you use an accent color.
  • Custom user identifier: Add support for custom user identifiers if you are planning to use the Transactional or the Custom Data APIs.
  • Token import: Import your existing tokens if you're coming from another push provider.