Intercepting notifications

Batch allows you to get pushes and their payload directly in your Cordova application, on both iOS and Android.

For that, whenever your application gets a push, Batch will emit a batchPushReceived event on the document. The push payload will be in the payload key of the event object.

var app = {
    bindEvents: function() {
        document.addEventListener('batchPushReceived', function(e) {
            var pushPayload = e.payload;
            // Process the payload as you wish here
        }, false);
    }
}

Batch will NOT emit this event until it is started. As soon as it is started, it will send you the payload of the push that started the app, if there is one.

Parsing the payload

Due to platform limitation, any top-level value that is not an object or an array will be a string. Values in an object or an array are fine and will keep their intended type.

This should not be a problem considered how types work in javascript, as long as you don't use strict equality comparaison (=== and !==)

For example, here is a custom payload how you would enter it in the dashboard or use in the REST API:

{
    "foo": "bar",
    "integer": 1,
    "boolean": true,
    "integers": "[1, 2]",
    "parameters": {
        "string": "string",
        "integer": 1
    }
}

Here is what your payload will look like when received in your app:

{
    "foo": "bar",
    "integer": "1",
    "boolean": "true",
    "integers": [1, 2], // Coerced into a native array
    "parameters": {
        "string": "string",
        "integer": 1 // Type preserved because in a sub-object
    }
}

Note: The payload is a representation of the complete push payload given by the push service. It may contain other key/value pairs, some internal to the OS/push service, some internal to Batch.

Differences between Android and iOS

While Batch unifies the native APIs for you, some differences between Android and iOS remain:

If your Cordova application gets a push while it is opened, you will get the batchPushReceived event immediatly on iOS (if Batch is started), whereas you will only get it on Android after the user taps on the notification.

If the app is closed when you get the push, you'll only get the payload associated to the notification the user tapped on on both platforms.

The payload will also be different, with the displayed message being available in different keys on both OSes.

Mobile landings

You might want to use batchPushReceived to display an in-app alert. Since 1.7.4, the Batch Cordova plugin does come with mobile landings, and might display a message on its own.

To know if the push has displayed a Mobile Landing, you can check the hasLandingMessage property of the event:

var app = {
    bindEvents: function() {
        document.addEventListener('batchPushReceived', function(e) {
            var pushPayload = e.payload;
            // Process the payload as you wish here
            var hasLandingMessage = e.hasLandingMessage; // this will be "true" if the message displayed a mobile landing
        }, false);
    }
}