Customizing notifications

Batch allows you to customize your notifications adding specific keys to the payload. The customization of the payload is available for Pro (and higher) users.

Since we allow the overriding of Apple's keys, you can use and override anything Apple accepts in the aps key. Apple's full documentation about the payload is located here

All of the following JSON examples go into the custom_payload field of both Transactional and Campaigns APIs.

Adding a badge

You can add a badge to your iOS notifications by adding a badge key to the payload of your push. Here is how it looks:

{"aps":{"badge":2}}

You should reset the badge count when the app is opened.

Adding actions buttons

You can add action buttons to your notification by adding a category key to the payload of your push. Here is how it looks:

{"aps":{"category":"CATEGORY_NAME"}}

We recommend you follow that guide to register categories.

Choosing a notification sound

You can set a custom sound for your notification by adding the sound key to your payload. All you need to do is to add your custom sound to your app bundle before choosing it. Here is how it looks:

{"aps":{"sound":"mysound.caf"}}

You can't remotely push new sounds to your app. The filename (or "default") must be a sound file already present in your app bundle. If it is missing, iOS will play the default sound.

Triggering a background refresh

iOS (7+) supports sending pushes that will wake up your app in the background. It works like background fetching, except that you control when your app will wake up.

This allows you to fetch new content (news feed, conversation list, etc) so your users won't have to wait for your app to sync when then open it.

First, you'll need to go in Xcode and enable "Remote notifications" as a Background Mode in your app's Capabilities:

Then, add "content-available":1 in your aps object:

{"aps":{"content-available":1}}

Warning
Users can disable background refresh for your application, or the system might not deliver it in some cases (like battery saving mode).You shouldn't rely on this to work at all times: always fetch data that you can fetch in a more reliable way when your app starts.

Sending silent notifications

Batch supports background notifications, which allow you to run actions for a limited amount of time without notifying the user.

Please keep in mind that the same restrictions apply as the ones described higher up for Background Refresh.

When calling our Campaign/Transactional APIs, add 'push_type': 'background' to the request's JSON body, and remove the message/messages/media keys.

Silent notifications are not supported from the dashboard yet. Using the legacy way to do silent notifications using only the custom payload will NOT work on iOS 13 and later.

Warning
As said earlier for background refresh, we advise against triggering local notifications in response to a silent notification. While they are handy, the delivery rate will suffer heavily due to the unreliableness of background refresh.

Showing foreground notifications (iOS 10+ only)

In order to show foreground notifications on iOS 10 and higher, you'll need to implement a UNUserNotificationCenterDelegate and tell iOS to display the system alert.

If you registered BatchUNUserNotificationCenterDelegate as your delegate, use the showForegroundNotifications property.

// If you did not use BatchUNUserNotificationCenterDelegateregisterAsDelegate() but instanciated your own instance, use it instead of `sharedInstance`.
BatchUNUserNotificationCenterDelegate.sharedInstance.showForegroundNotifications = true

You can also do so with your own UNUserNotificationCenterDelegate:

• Create a class that implements UNUserNotificationCenterDelegate
• Override userNotificationCenter(center:willPresentNotification:withCompletionHandler) and return at least the alert type to its completion handler
• Call Batch's appropriate methods so you don't break any features
• Set it as the default UNUserNotificationCenter's delegate

A sample UNUserNotificationDelegate along with how to show a foreground push is detailed in Intercepting Notifications.