Migrating from 4.0

Batch Cordova Plugin 5.0 is a major release, which introduces breaking changes from 4.x. This guide describes how to update the plugin in an application already using Batch Cordova Plugin 4.0.
If you need to migrate from 2.x, please follow Migrating from 2.3 first.

Asynchronous methods

Any method that used to take a callback parameter have been changed to take no parameter and return a Promise.
Those promises will be resolved with an empty result if the requested data is not available.


batch.user.getInstallationID((installationID) => { /* ... */ })


batch.user.getInstallationID().then((installationID) => { /* ... */ })
// or
await batch.user.getInstallationID()

The following methods are affected:

  • batch.user.getInstallationID()
  • batch.push.getLastKnownPushToken()


Batch Cordova's Inbox module has been rewritten to support pagination, bringing it closer to the native implementation. Marking notifications as read or deleted is now supported.

As a result, the old inbox methods have been removed:

  • batch.inbox.fetchNotifications()
  • batch.inbox.fetchNotificationsForUserIdentifier()

Fetching Inbox notifications is now done in three steps:

  • Instanciate an installation or user fetcher and keep a reference to its instance.
  • Fetch notifications.
  • Dispose of the instance once you're done to free up memory.

Building on this, you will be able to fetch more pages or mark notifications as read/deleted

To learn more, please follow the new Inbox documentation.

iOS batchPushReceived event payload

Batch Cordova 3.x and 4.x have an issue where the batchPushReceived event parameters are different between iOS and Android:

  • On Android (or iOS on 2.x), the payload was merged at the root of the event data
  • On iOS, the payload was under the "payload" key.

As this was not the intended behaviour, version 5.0 fixes this by making iOS merge the payload at the root as expected.

iOS Notification Registration

In an effort to reduce the differences between the Cordova Plugin and the Native SDK, batch.push.registerForRemoteNotifications() has been split into two methods:

  • batch.push.refreshToken(), which should be called on every application start.
  • batch.push.requestNotificationAuthorization(), which should be called when you want to trigger the iOS notification permission request.

batch.push.requestProvisionalNotificationAuthorization() has also been added, which allows your application to request the provisional notification authorization.

iOS Foreground Notifications (Capacitor)

On iOS, Batch Cordova 3.x and 4.x implement a UNUserNotificationCenterDelegate that proxies a previously set delegate (if present) and honored its decision to display or hide foreground notifications.

This was done so that developers who implemented this class natively did not notice an unexpected change in behaviour.

As Ionic Capacitor has added a delegate implementation that is set by default, Batch always forwarded the decision to their implementation, meaning that batch.push.setiOSShowForegroundNotifications() didn't work anymore.

As Capacitor requires the installation of a plugin to change this, Batch now overrides Capacitor's foreground notification setting when and only if setiOSShowForegroundNotifications() is called.