Customization

Badge Counts

You can specify the desired badge count when you compose a push notification through Braze’s dashboard. You may also update your badge count manually through your application’s applicationIconBadgeNumber property or through the remote notification payload. Braze will also clear the badge count when a Braze notification is received while the app is foregrounded. If you do not have a plan for clearing badges as part of normal app operation or by sending pushes which clear the badge, you should clear the badge when the app becomes active by adding the following code to your app’s applicationDidBecomeActive: delegate method:

1
[UIApplication sharedApplication].applicationIconBadgeNumber = 0;
1
UIApplication.shared.applicationIconBadgeNumber = 0

Please note that setting the badge number to 0 will also clear up notifications in the notification center. So even if you don’t set badge number in push payloads, you can still set the badge number to 0 to remove the push notification(s) in the notification center after users clicked on the push.

Action Buttons

In addition to providing a set of default push categories, Braze supports custom notification categories and actions. Once you register categories in your application, you can use the Braze dashboard to send notification categories to your users.

For an example of setting up custom actions and categories, please see the setupRemoteNotificationForiOS10 or setupRemoteNotificationForiOS8And9 methods within the AppDelegate.m file of Stopwatch.

If you haven’t migrated to iOS 10, please see this alternative categories documentation.

These categories can then be assigned to push notifications via our dashboard to trigger the action button configurations of your design. Here’s an example that leverages the “LIKE_CATEGORY” displayed on the device!

Push Example with Buttons

Sample Braze Apple Push Payload

When Braze sends a push notification, the payload will look like this. You should avoid handling a top-level dictionary called ab or aps in your application:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  aps: {
    alert: {
     body: "your push message",
     title: "your message title"
    },
    badge: 1,
    ...
  },
  ab: {
    att: { // optional, required for campaigns with iOS 10 rich notifications
      url: (optional, string) attachment url,
      type: (optional, string) attachment filetype
    },
    ab_cat: { // optional, required for campaigns with push action buttons
      <action_id>: (required) {
        a_t: (required, string) click action type,
        a_uri: (optional, string) uri to open when the push action button is clicked,
        a_use_webview: (optional, boolean) open the a_uri in a UIWebView if true
      },
      ... Other Buttons ...
    },
   }
  ab_uri: (optional, string) uri to open when push notification is clicked,
  ab_use_webview: (optional, boolean) open the ab_uri in a UIWebView if true,
  <custom_key>: "foo",
  ... Custom key-value  Pairs ...
}

the alert can also just be a string, which will be the push message text.

In the case that your push notification does not have a campaign ID, the key c will have the value NSNull. This value is necessary and should not be sanitized or removed. Some cases where there is no campaign ID are sending a push from an API campaign, a test push from the dashboard, or a test curl.

Custom Sounds and Push

Step 1: Hosting the Sound in the App

Custom push notification sounds must be hosted locally within the main bundle of the client application. The following audio data formats are accepted:

  • Linear PCM
  • MA4
  • µLaw
  • aLaw

You can package the audio data in an aiff, wav, or caf file. Then, in Xcode, add the sound file to your project as a nonlocalized resource of the application bundle.

You may use the afconvert tool to convert sounds. For example, to convert the 16-bit linear PCM system sound Submarine.aiff to IMA4 audio in a CAF file, use the following command in the Terminal application:

1
afconvert /System/Library/Sounds/Submarine.aiff ~/Desktop/sub.caf -d ima4 -f caff -v

You can inspect a sound to determine its data format by opening it in QuickTime Player and choosing Show Movie Inspector from the Movie menu.

Custom sounds must be under 30 seconds when played. If a custom sound is over that limit, the default system sound is played instead.

Step 2: Providing the Dashboard with a Protocol URL for the Sound

Your sound must be hosted locally within the app. You must specify a Protocol URL which directs to the location of the sound file in the app within the “Sound” field in the push composer. Specifying “default” in this field will play the default notification sound on the device. This can be specified via our Messaging API or our dashboard under “Advanced Settings” in the push composer wizard as pictured below:

Push Notification Sound

If the specified sound file doesn’t exist or the keyword ‘default’ is entered, Braze will use the default device alert sound. Aside from our dashboard, sound can also be configured via our our Messaging API. For additional information see the Apple Developer Documentation regarding “Preparing Custom Alert Sounds”.

Ignoring Braze’s Internal Push Notifications

Braze uses silent push notifications for internal implementation of certain advanced features. For most integrations, this requires no changes on your app’s behalf. However, if you integrate a Braze feature that relies on internal push notifications (i.e., uninstall tracking or geofences), you may want to update your app to ignore Braze’s internal pushes.

If your app takes automatic actions on application launches or background pushes, you should consider gating that activity so that it’s not triggered by Braze’s internal push notifications. For example, if you have logic that calls your servers for new content upon every background push or application launch, you likely would not want Braze’s internal pushes triggering that because you would incur unnecessary network traffic. Furthermore, because Braze sends certain kinds of internal pushes to all users at approximately the same time, not gating network calls on launch from internal pushes could introduce significant server load.

Checking Your App for Automatic Actions

You should check your application for automatic actions in the following places and update your code to ignore Braze’s internal pushes:

  1. Push Receivers. Background push notifications will call application:didReceiveRemoteNotification:fetchCompletionHandler: on the UIApplicationDelegate.
  2. Application Delegate. Background pushes can launch suspended apps into the background, triggering the application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: methods on your UIApplicationDelegate. You can check the launchOptions of these methods to determine if the application has been launched from a background push.

Using Braze’s Internal Push Utility Methods

You can use the utility methods in ABKPushUtils to check if your app has received or was launched by a Braze internal push. isAppboyInternalRemoteNotification: will return YES on all Braze internal push notifications, while isUninstallTrackingRemoteNotification: and isGeofencesSyncRemoteNotification: will return YES for uninstall tracking and geofences sync notifications, respectively. See ABKPushUtils.h for method declarations and our Stopwatch sample application for example implementations.

Implementation Example

1
2
3
4
5
6
7
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  NSDictionary *pushDictionary = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];
  BOOL launchedFromAppboyInternalPush = pushDictionary && [ABKPushUtils isAppboyInternalRemoteNotification:pushDictionary];
  if (!launchedFromAppboyInternalPush) {
    // ... Gated logic here (e.g., pinging your server to download content) ...
  }
}
1
2
3
4
5
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
  if (![ABKPushUtils isAppboyInternalRemoteNotification:userInfo]) {
    // ... Gated logic here (e.g., pinging server for content) ...
  }
}
1
2
3
4
5
6
7
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
  let pushDictionary = launchOptions?[UIApplicationLaunchOptionsKey.remoteNotification] as? NSDictionary as? [AnyHashable : Any] ?? [:]
  let launchedFromAppboyInternalPush = ABKPushUtils.isAppboyInternalRemoteNotification(pushDictionary)
  if (!launchedFromAppboyInternalPush) {
    // ... Gated logic here (e.g., pinging your server to download content) ...
  }
}
1
2
3
4
5
6
7
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable : Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
  if (!ABKPushUtils.isAppboyInternalRemoteNotification(userInfo)) {
    // ... Gated logic here (e.g., pinging server for content) ...
  }
}

Extracting Data from Push Notification Key-Value Pairs

Braze allows you to send additional key-value pairs along with a push notification via your application within the extras property. Please see the following example code for extracting data from that key-value pair:

1
2
3
4
5
6
7
- (void)handleExtrasFromPush:(NSDictionary *)notification {
  NSLog(@"A push was received");
  if (notification != nil && [notification objectForKey:@"Some_Key"] !=[NSNull null] && [[notification objectForKey:@"Some_Key"] length] > 0 ) {
    NSString *value = [NSString stringWithFormat:@"%@",[notification objectForKey:@"Some_Key"]];
    // Here based on the extras key-value pair, you can run some arbitrary code.
  }
}
WAS THIS PAGE HELPFUL?