iOS > Advanced

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

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.

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:
Xcode Project 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

By combining a background fetch, a null sound and a null alert, you can send fully silent pushes, which allow you to run actions for a limited amount of time without notifying the user.

Here are the keys you need to add to your payload to send silent notifications:

{"aps":{"content-available": 1, "sound": null, "alert": null}}

As mentioned in Apple's documentation, you should exclusively use APNS normal priority (API/dashboard) to send silent push notification.

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.

You can achieve that by:

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

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