SDK integration

Batch Cordova is compatible with:

  • cordova 9.0.0+
  • cordova-android 9.0.0+
  • cordova-ios 6.0.0+

Please see the native SDK documentation for minimum OS version per platform.

Ionic Cordova and Ionic Capacitor are also supported:

  • Ionic 6.0+
  • Ionic Capacitor (Core and CLI) 2.4+

Other platforms supported by Cordova are not supported by Batch.

Setting up the SDK

# Cordova
cordova plugin add @batch.com/cordova-plugin

# Ionic Cordova
ionic cordova plugin add @batch.com/cordova-plugin

# Ionic Capacitor
npm i @batch.com/cordova-plugin
npx cap sync

Note: The cordova plugin internal name is 'com.batch.cordova'. If you need to manipulate the plugin (for example, with cordova plugin remove), you might need to use this name.

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:

function onDeviceReady() {
    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

Project setup

Batch requires androidx to be enabled in your project.
How to enable it depends on your environment:

  • Cordova Android 9.0 has native support for androidx: add <preference name="AndroidXEnabled" value="true" /> to your config.xml.

If you're using a lower Cordova Android version, please update if possible. Using Cordova Android 8 with an androidx plugin might work but is unsupported.

  • Depending on your installed plugins, you might need to add an extra plugin: ionic cordova plugin add cordova-plugin-androidx-adapter. Ionic Cordova users are required to add this plugin.
  • Ionic Capacitor users have nothing to do.

Firebase Cloud Messaging

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

Cordova / Ionic Cordova

Due to the variety of Firebase solutions in the Cordova ecosystem, Batch requires that FCM is added in your application using a separate plugin or manually.

We recommend using cordova-plugin-firebase-messaging.

Note: Please make sure that the plugin you're using doesn't use the native firebase-messaging library version 22.0 or greater.
If so, please downgrade or add com.google.firebase:firebase-iid:21.1.0 in your native dependencies. A future SDK release will support FCM tokens.

One caveat is that most Cordova Firebase plugins add FCM to both Android and iOS. This might not be desired: Batch does not require Firebase on iOS, so you might not want to ship Firebase with your iOS application.

It is possible to add FCM to your project manually. Open up your config.xml and add these lines:

<platform name="android">
  <preference name="GradlePluginGoogleServicesEnabled" value="true" />
  <preference name="GradlePluginGoogleServicesVersion" value="4.3.3" />

  <resource-file src="build-extras.gradle" target="app/build-extras.gradle" />
</platform>

Note: Make sure that your platforms/android folder do not already have a build-extras.gradle file in it, as this will override it. If you do, either merge the files or remove the resource-file config tag.

If you're using an older Cordova version, you might need extra plugins such as cordova-plugin-androidx , cordova-support-google-services and cordova-support-android-plugin.

Then, at the root of your application project, create a new file called build-extras.gradle and add the following in it:

repositories {
    mavenCentral()
    maven {
        url "https://maven.google.com"
    }
}

dependencies {
    implementation "androidx.appcompat:appcompat:1.2.+"
    implementation "com.google.firebase:firebase-messaging:21.0.+"
    // Uncomment this line if you want Advertising ID support
    //implementation "com.google.android.gms:play-services-ads-identifier:+"
    // Uncomment this line if you use firebase-messaging 22 or greater
    //implementation "com.google.firebase:firebase-iid:21.1.0"
}

Note: This documentation isn't updated with androidx.core and firebase-messaging's latest versions. Please use up to date versions of these dependencies when possible.

Once you've set up FCM, you will need to configure google-services.json. How to add it into your app depends on your plugin, but common steps are:

  • Download google-services.json and save it in your app's root directory.

If you don't have this file yet, please follow the "Manually add Firebase" part of this documentation until you get it.

  • Tell Cordova to copy it. Your firebase plugin should come with instructions on how to do so.

If not, the following config.xml items might work:

<platform name="android">
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>
Ionic Capacitor

Open android/variables.gradle and add firebaseMessagingVersion = "21.0.1" if missing. You may want to use the latest firebase-messaging version.

ext {
    minSdkVersion = 21
    ...
    cordovaAndroidVersion = '7.0.0'
    firebaseMessagingVersion = '21.0.1'
}

Then, please follow Capacitor's Android Push Notifications documentation to configure Firebase.

Note: If you're using firebase-messaging >= 22.0, please add the Firebase Installations library to your dependencies in your build.gradle or you will not be able to receive push notifications:
implementation "com.google.firebase:firebase-iid:21.1.0". A future SDK release will bring support for FCM Tokens.

Setting your small icon

Follow the Customizing Batch notifications guide to display your notification icon correctly on Android.

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.

// Typescript users can import the typings by uncommenting the next line
// import type {} from '@batch.com/cordova-plugin';

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

Rich Push

In order to enable rich content in notification (such as images), a Notification Service extension must be added in the Xcode project.
First, locate your Xcode project: it should be located platforms/ios/ and be named <yourapp>.xcworkspace.

Then, follow the native rich push setup documentation.

Note: This needs to be performed each time the platforms/ios directory is regenerated.

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.