Push integration

Step 1: Configure push notifications

Before you can send an iOS push notification using Braze, you must provide your .p8 push notification file provided by Apple. As described on the Apple developer documentation:

1. In your Apple developer account, go to Certificates, Identifiers & Profiles.
2. Under Keys, select All and click the add button (+) in the upper-right corner.
3. Under Key Description, enter a unique name for the signing key.
4. Under Key Services, select the Apple Push Notification service (APNs) checkbox, then click Continue. Click Confirm.
5. Note the key ID. Click Download to generate and download the key. Make sure to save the downloaded file in a secure place, as you cannot download this more than once.
6. In Braze, go to Settings > App Settings and upload the .p8 file under Apple Push Certificate. You can upload either your development or production push certificate. To test push notifications after your app is live in the App Store, its recommended to set up a separate workspace for the development version of your app.
7. When prompted, enter your app’s bundle ID, key ID, and team ID, then click Save.

Step 2: Enable push capabilities

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

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

Step 3: Register for push notifications

The appropriate code sample must be included within your app’s application:didFinishLaunchingWithOptions: delegate method for your users’ device to register with APNs. Ensure that you call all push integration code in your application’s main thread.

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

Using UserNotification framework (iOS 10+)

If you are using the UserNotifications framework (recommended) introduced in iOS 10, add the following code to the application:didFinishLaunchingWithOptions: method of your app delegate.

• objective-c
• swift

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
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)
  }
  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

If you are not using the UserNotifications framework, add the following code to the application:didFinishLaunchingWithOptions: method of your app delegate:

• objective-c
• swift

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:

• objective-c
• swift

1
[[Appboy sharedInstance] registerDeviceToken:deviceToken];

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. Ensure you call all push integration code in your application’s main thread.

iOS 10+

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

• objective-c
• swift

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

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

1
2
3
4
5
6
7
8
9
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  if (@available(iOS 14.0, *)) {
    completionHandler(UNNotificationPresentationOptionList | UNNotificationPresentationOptionBanner);
  } else {
    completionHandler(UNNotificationPresentationOptionAlert);
  }
}

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

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

1
2
3
4
5
6
7
8
9
func userNotificationCenter(_ center: UNUserNotificationCenter,
                              willPresent notification: UNNotification,
                              withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
  if #available(iOS 14.0, *) {
    completionHandler([.list, .banner]);
  } else {
    completionHandler([.alert]);
  }
}

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:

• objective-c
• swift

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

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

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

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

Step 6: 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.

Step 7: Unit tests (optional)

To add test coverage for the integration steps you’ve just followed, implement push unit testing.