Push Integration

Step 1: Configure Push Notifications

Before you can send an iOS push notification using Braze, you must provide your Push notification file or certificate from Apple. You may present either a .p8 file (recommended) or a .p12 certificate.

Using a .p12 Certificate (Legacy)

Alternately, you may utilize Apple’s older authentication scheme (.p12 SSL certificates). Unlike the .p8 solution described above, these certificates automatically expire every year and will require you to regenerate and re-upload them. Braze will send you email reminders as the certificate approaches expiration to help your notifications continue uninterrupted, but because this is a manual process we recommend utilizing the above-described .p8 authentication scheme instead. However, if you still wish to, you may configure and upload .p12 certificates as described here:

Step 1: Generate Certificate Signing Request

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

iOSPush3

  1. Select your application.
  2. If push notifications are not enabled, click Edit to update the app settings AppleProvisioningOptions
  3. Tick the Enable check box and click Create Certificate under the Production SSL Certificate ![iOSPush3][4]
  4. 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 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.
  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 production 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 2: Enable Push Capabilities

In your project settings, ensure that under the Capabilities tab your Push Notifications capability is toggled on, as described on this page.

enable push notification

If you are using Xcode 8 and have separate development and production push certificates, please make sure to uncheck the Automatically manage signing box in the General tab. This will allow you to choose different provisioning profiles for each of your build configurations, as Xcode’s automatic code signing feature only does development signing. xcode 8 auto signing

Step 3: Register for Push Notifications

The appropriate code sample below must be included within your app’s application:didFinishLaunchingWithOptions: delegate method for your users’ device to register with APNs.

Braze also provides default push categories for push action button support, which must be manually added to your push registration code. See our push action buttons documentation for additional integration steps.

If you’ve implemented a custom push prompt as described in our push best practices, make sure that you’re calling the following code EVERY time the app runs after they grant push permissions to your app. Apps need to re-register with APNs as device tokens can change arbitrarily.

Using UserNotification Framework (iOS 10+)

If you are using the UserNotifications framework (recommended) that was introduced in iOS 10, use the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
if (floor(NSFoundationVersionNumber) > NSFoundationVersionNumber_iOS_9_x_Max) {
  UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
  center.delegate = self;
  UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
  if (@available(iOS 12.0, *)) {
  options = options | UNAuthorizationOptionProvisional;
  }
  [center requestAuthorizationWithOptions:options
                        completionHandler:^(BOOL granted, NSError * _Nullable error) {
                          [[Appboy sharedInstance] pushAuthorizationFromUserNotificationCenter:granted];
  }];
  [[UIApplication sharedApplication] registerForRemoteNotifications];
} else {
  UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeBadge | UIUserNotificationTypeAlert | UIUserNotificationTypeSound) categories:nil];
  [[UIApplication sharedApplication] registerForRemoteNotifications];
  [[UIApplication sharedApplication] registerUserNotificationSettings:settings];
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
if #available(iOS 10, *) {
  let center = UNUserNotificationCenter.current()
  center.delegate = self as? UNUserNotificationCenterDelegate
  var options: UNAuthorizationOptions = [.alert, .sound, .badge]
  if #available(iOS 12.0, *) {
    options = UNAuthorizationOptions(rawValue: options.rawValue | UNAuthorizationOptions.provisional.rawValue)
  }
  center.requestAuthorization(options: options) { (granted, error) in
    Appboy.sharedInstance()?.pushAuthorization(fromUserNotificationCenter: granted)
    print("Permission granted.")
  }
  UIApplication.shared.registerForRemoteNotifications()
} else {
  let types : UIUserNotificationType = [.alert, .badge, .sound]
  let setting : UIUserNotificationSettings = UIUserNotificationSettings(types:types, categories:nil)
  UIApplication.shared.registerUserNotificationSettings(setting)
  UIApplication.shared.registerForRemoteNotifications()
}

Without UserNotifications Framework

When not using the UserNotifications framework, use the following:

1
2
3
UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeBadge | UIUserNotificationTypeAlert | UIUserNotificationTypeSound) categories:nil];
[[UIApplication sharedApplication] registerForRemoteNotifications];
[[UIApplication sharedApplication] registerUserNotificationSettings:settings];
1
2
3
4
let types : UIUserNotificationType = UIUserNotificationType.Badge | UIUserNotificationType.Sound | UIUserNotificationType.Alert
var setting : UIUserNotificationSettings = UIUserNotificationSettings(forTypes: types, categories: nil)
UIApplication.shared.registerUserNotificationSettings(setting)
UIApplication.shared.registerForRemoteNotifications()

Step 4: Register Push Tokens With Braze

Once APNs registration is complete, the following method must be altered to pass the resulting deviceToken to Braze so the user becomes enabled for push notifications:

Add the following code to your application:didRegisterForRemoteNotificationsWithDeviceToken: method:

1
[[Appboy sharedInstance] registerDeviceToken:deviceToken];

Add the following code to your app’s application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method:

1
Appboy.sharedInstance()?.registerDeviceToken(deviceToken)

Step 5: Enable Push Handling

The following code passes received push notifications along to Braze and is necessary for logging push analytics and link handling.

iOS 10+

When building against iOS 10+ we recommend you integrate the UserNotifications framework and do the following:

Add the following code to your application’s application:didReceiveRemoteNotification:fetchCompletionHandler: method:

1
2
3
[[Appboy sharedInstance] registerApplication:application
                didReceiveRemoteNotification:userInfo
                      fetchCompletionHandler:completionHandler];

Next, add the following code to your app’s (void)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method:

1
2
3
[[Appboy sharedInstance] userNotificationCenter:center
                 didReceiveNotificationResponse:response
                          withCompletionHandler:completionHandler];

Foreground Push Handling

In iOS 10, you can display a push notification while the app is in the foreground by implementing the following delegate method and returning UNNotificationPresentationOptionAlert to the completionHandler:

1
2
3
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler

In this case, if the user clicks the displayed foreground push, the new iOS 10 push delegate method userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: will be called and Braze will log a click for that push.

Add the following code to your app’s application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method:

1
2
3
Appboy.sharedInstance()?.register(application,
                                            didReceiveRemoteNotification: userInfo,
                                            fetchCompletionHandler: completionHandler)

Next, add the following code to your app’s userNotificationCenter(_:didReceive:withCompletionHandler:) method:

1
2
3
Appboy.sharedInstance()?.userNotificationCenter(center,
                                               didReceive: response,
                                               withCompletionHandler: completionHandler)

Foreground Push Handling

In iOS 10, you can display a push notification while the app is in the foreground by implementing the following delegate method and returning UNNotificationPresentationOptionAlert to the completionHandler in the appropriate view controller class:

1
2
3
4
5
6
func userNotificationCenter(_ center: UNUserNotificationCenter,
                willPresent notification: UNNotification,
      withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    completionHandler([.alert, .badge, .sound])
}

In this case, if the user clicks the displayed foreground push, the new iOS 10 push delegate method userNotificationCenter(_:didReceive:withCompletionHandler:) will be called and Braze will log a click for that push.

Pre-iOS 10

iOS 10 updated behavior such that it no longer calls application:didReceiveRemoteNotification:fetchCompletionHandler: when a push is clicked. For this reason, if you don’t update to building against iOS 10+ and use the UserNotifications framework, you have to call Braze from both old-style delegates, which is a break from our previous integration.

For apps building against SDKs < iOS 10, use the following instructions:

To enable open tracking on push notifications, add the following code to your app’s application:didReceiveRemoteNotification:fetchCompletionHandler: method:

1
2
3
[[Appboy sharedInstance] registerApplication:application
                didReceiveRemoteNotification:userInfo
                      fetchCompletionHandler:completionHandler];

To support push analytics on iOS 10, you must also add the following code to your app’s application:didReceiveRemoteNotification: delegate method:

1
2
[[Appboy sharedInstance] registerApplication:application
                didReceiveRemoteNotification:userInfo];

To enable open tracking on push notifications, add the following code to your app’s application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method:

1
2
3
Appboy.sharedInstance()?.register(application,
  didReceiveRemoteNotification: userInfo,
  fetchCompletionHandler: completionHandler)

To support push analytics on iOS 10, you must also add the following code to your app’s application(_:didReceiveRemoteNotification:) delegate method:

1
2
Appboy.sharedInstance()?.register(application,
  didReceiveRemoteNotification: userInfo)

Step 6: Verify Code Modifications

Verify the code modifications you made against this sample AppDelegate.m file. We also strongly advise looking through the below section on customization to determine if any additional changes need to be implemented.

Step 7: Deep Linking

Deep linking from a push into the app is automatically handled via our standard push integration documentation. If you’d like to learn more about how to add deep links to specific locations in your app, see our Advanced Use Cases section on Deep Linking for iOS.

WAS THIS PAGE HELPFUL?
New Stuff!