Push Notifications

A push notification is an out-of-app alert that appears on the user’s screen when an important update occurs. Push notifications are a valuable way to provide your users with time-sensitive and relevant content or to re-engage them with your app.

Sample push notification:

Sample Push

Check out Braze Academy for additional best practices.

Step 1: Configure the Apple Developer Settings

  1. Navigate to the iOS Provisioning Portal
  2. Select Identifiers > App IDs in the left sidebar


  3. Select your application
  4. If push notifications are not enabled, click Edit to update the app settings AppleProvisioningOptions
  5. Tick the Enable check box and click Create Certificate under the Production SSL Certificate iOSPush3
  6. Follow the instructions from the SSL certificate assistant. You should now see a green status to indicate that push is enabled. You must update your provisioning profile for the app after you create your SSL certificates. A simple “Refresh” in the organizer will accomplish this.

Step 2: Export Your Push Certificate

  1. Download the production push certificate that you just created and open it with the Keychain Access application
  2. In Keychain Access, click on My Certificates and locate your push certificate private key
  3. Export it as a .p12 file and use a temporary, unsecure password (you will need this password when uploading your certificate to Braze)
  4. Navigate to the App Settings page in the dashboard and upload your production certificate. push upload example

    You can upload either your development or universal push certificates to the dashboard for your distribution provisioning profile apps, but you can only have one active at a time. As such, if you wish to do repeated testing of push notifications once your app goes live in the App Store, we recommend setting up a separate App Group or App for the development version of your app.

Step 3: Customize Push Notification Settings

Braze provides a native Unity solution for automating the Unity iOS push notification integration. To take advantage of this option, please ensure that you have followed the Initial SDK Setup steps on setting your Braze API key through Unity.

Step 1: Open Braze Configuration Settings

In the Unity Editor, open the Braze Configuration Settings by navigating to Braze > Braze Configuration.

Step 2: Integrating Push With Braze

Check “Integrate Push With Braze” to automatically register users for push notifications, pass push tokens to Braze, track analytics for push opens, and take advantage of Braze’s default push notification handling.

Integrate Push With Braze

Users who have not yet opted-in to push notifications will be prompted to opt-in upon opening your application. To disable the automatic opt-in prompt and manually register users for push, see Disabling Automatic Push Registration below.

If you do not check this option, you will not be able to send your users push notifications from the Braze dashboard without following the manual push notification integration instructions.

Disabling Automatic Push Registration

Check “Disable Automatic Push Registration” if you would like to manually register users with APNs (Apple Push Notification Service). Unity provides NotificationServices.RegisterForNotifications to do this from Unity.

Disable Automatic Push Registration

If you check this option, make sure that you are registering users for push notifications EVERY time the application runs after users have granted push permissions to your app. Apps need to re-register with APNs as device tokens can change arbitrarily.

Enabling Background Push

Check “Enable Background Push” if you would like to enable background mode for push notifications. This allows the system to wake your application from the Suspended state when a push notification arrives, enabling your application to download content in response to push notifications. Checking this option is required for Braze’s uninstall tracking functionality.

Enabling Background Push

If you build your Xcode project with “Enable Background Push” checked and then later uncheck this option, you will need to either manually disable background push or choose “Replace” when rebuilding your iOS project. You can manually disable background push by removing remote-notifications from the UIBackgroundModes array in your Info.plist.

Step 3: Setting Push Listeners

If you would like to pass push notification payloads to Unity or take additional steps when a user receives a push notification, Braze provides the option of setting push notification listeners.

Push Received Listener

The Push Received listener is fired when a user receives a push notification while they are actively using the application (i.e., the app is foregrounded). To send the push payload to Unity, set the name of your Game Object and Push Received listener callback method under the “Set Push Received Listener” foldout, like so:

Push Received Listener

For a sample implementation, take a look at the PushNotificationReceivedCallbackForiOS in AppboyBindingTester.cs.

Push Opened Listener

The Push Opened listener is fired when a user launches the app by clicking on a push notification. To send the push payload to Unity, set the name of your Game Object and Push Opened listener callback method under the “Set Push Opened Listener” foldout, like so:

Push Opened Listener

For a sample implementation, take a look at the PushNotificationOpenedCallbackForiOS in AppboyBindingTester.cs.

Manual Push Integration

Step 1: Update Application Code

  • Add the code below to your application:didRegisterForRemoteNotificationsWithDeviceToken method

    [[Appboy sharedInstance] registerDeviceToken:deviceToken];
  • Call the registerForRemoteNotificationTypes: in your application:didFinishLaunchingWithOptions: method

      [[UIApplication sharedApplication] registerForRemoteNotificationTypes:
                (UIRemoteNotificationTypeAlert |
                 UIRemoteNotificationTypeBadge |
      [[AppboyUnityManager sharedInstance] addPushReceivedListenerWithObjectName:@"Your Unity Game Object Name" callbackMethodName:@"Your Unity Call Back Method Name"];
      [[AppboyUnityManager sharedInstance] addPushOpenedListenerWithObjectName:@"Your Unity Game Object Name" callbackMethodName:@"Your Unity Call Back Method Name"];
  • In your app delegate, add the code below to your application:didReceiveRemoteNotification method:

Method to Count Opens while Foregrounded

Braze will use this code to determine if a push notification was opened. If the app is foregrounded and a push notification comes in, Braze will still count the open.

[[AppboyUnityManager sharedInstance] registerApplication:application

Alternate Method to Disregard Opens while Foregrounded

If you don’t want to count opens for pushes that come in while the app is foregrounded use the following method instead:

UIApplicationState state = [application applicationState];
if (state != UIApplicationStateActive) {
 [[AppboyUnityManager sharedInstance] registerApplication:application

Step 2: Verify Code Modifications

Verify the code modifications you made against this sample AppController.mm file.

Push Customization

iOS Badge Counts

If badge counts are enabled, Braze will only clear the badge count when the app is opened directly from a Braze push notification. This is to avoid interfering with any other badges stemming from other notifications within the app.

Manually Clearing the Badge Count

[UIApplication sharedApplication].applicationIconBadgeNumber = 0;

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 in your application:

  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 webview 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 webview if true,
  <custom_key>: "foo",
  ... Custom key-value  Pairs ...

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:

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 pictured below:

Push Notification Sound

For additional information see the Apple Developer Documentation regarding “Preparing Custom Alert Sounds” as well as our resources regarding the use of “Protocol URLs.”

Deep Linking to In-App Resources

See our documentation on Deep Linking in iOS.

New Stuff!