Push Notifications

Push Notifications

The Zendesk SDK for iOS uses Apple Push Notification service (APNs) for push notifications. The following steps will guide you, or your development team, through the process of setting up push notifications for the Zendesk SDK in your app.

Step 1 - Creating your .p12 certificate on the Apple Developer site

For the steps below, you must be logged in to your Apple Developer account. If you don’t have a developer account yet, you can enroll here.

1. Log in to Apple Developer Member Center, and navigate to the certificates list.
2. Click the + button at the top of the page to create a new certificate, and select Apple Push Notification service SSL (Sandbox & Production).
3. Select your app ID from the dropdown and click continue.
4. Follow the instructions to generate a Certificate Signing Request (CSR) using Keychain Access, and upload it to generate your certificate.
5. Once the certificate is ready, download it to your computer and double-click it to open it in Keychain Access.
6. Right click on the certificate you created, and select Export "Apple Push Services: {your-app-id}".
7. Choose a password, if desired, and save the .p12 file to your computer.

Important: We do not support the use of Sandbox only Certificates. You will have to use a certificate with Production environment in order to enable Push Notifications.
We don't support any other way to generate to generate the CSR nor the .p12 files.
The documentation required by Apple to implement Push capabilities in your app is not provided by Zendesk, but can be found on Apple's Developer website.
The same applies for some portions of Xcode configuration beyond adding the Push Notification Capability (see below).

Step 2 - Adding your .p12 certificate in the Zendesk Admin Center

Now that you have created your .p12 certificate, it will need to be uploaded to the Zendesk Admin Center by an admin on your Zendesk account. If you are not an admin, please contact an admin on your account to assist you with this step.

If you already have iOS messaging enabled

1. In the Zendesk Admin Center, click the Channels icon, then click Messaging.
2. Click iOS, then click the Notifications tab.
3. Drag and drop your .p12 certificate or click the link to locate and upload your certificate.

If you don’t have iOS messaging enabled

1. In the Zendesk Admin Center, click the Channels icon, then click Messaging Setup.
2. On the Set up messaging page, select the checkbox to Enable messaging for your account.
3. Click Manage Channels.
4. Click Add Channel, then click iOS.
5. Follow the prompts to configure the channel, then click Finish.
6. Click the iOS channel if it is not already open, and click the Notifications tab.
7. Drag and drop your .p12 certificate or click the link to locate and upload your certificate.

Step 3 - Add the push notifications capability to your project

1. Select your project target.

2. Go to the Signing & Capabilities tab.

3. Add the Push Notifications capability with the + Capability button.

   

Step 4 - Set the APS Environment entitlement

This is added automatically when you add the Push Notifications capability. Check the app's .entitlements file to make sure an APS Environment key exists and that it is using production.

Step 5 - Request authorization for push notifications from your user

Register for push notifications using UNUserNotificationCenter in your AppDelegate in application(didFinishLaunchingWithOptions).

Swift

import UserNotifications

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    registerForPushNotifications()
    return true
}

private func registerForPushNotifications() {
    let notificationCenter = UNUserNotificationCenter.current()
    notificationCenter.delegate = self
    notificationCenter.requestAuthorization(options: [.alert, .sound, .badge]) { allowed, _ in
        guard allowed else { return }

        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}

Objective-C

#import <UserNotifications/UserNotifications.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [self registerForPushNotifications];
    return YES;
}

- (void)registerForPushNotifications {
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
      center.delegate = self;
      [center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge)
         completionHandler:^(BOOL allowed, NSError * _Nullable error) {
        if (allowed) {
          dispatch_async(dispatch_get_main_queue(), ^{
              [[UIApplication sharedApplication] registerForRemoteNotifications];
          });
        }
    }];
}

Step 6 - Add the Zendesk SDK to your app

Add the Zendesk SDK and update the PushNotifications class with the received device token.

Override application(didRegisterForRemoteNotificationsWithDeviceToken) in your AppDelegate.

Swift

import ZendeskSDKMessaging

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    PushNotifications.updatePushNotificationToken(deviceToken)
}

Objective-C

#import <ZendeskSDKMessaging/ZendeskSDKMessaging.h>

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [ZDKPushNotifications updatePushNotificationToken:deviceToken];
}

Step 7 - Show push notifications in your app

Conform to the UNUserNotificationCenterDelegate.

Swift

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate

Objective-C

@interface AppDelegate : UIResponder <UIApplicationDelegate, UNUserNotificationCenterDelegate>

Implement userNotificationCenter(willPresent) to display a notification while the app is in the foreground.

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification,
                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo

    // This checks whether a received push notification should be displayed by Messaging
    let shouldBeDisplayed = PushNotifications.shouldBeDisplayed(userInfo)

    switch shouldBeDisplayed {
    case .messagingShouldDisplay:
        // This push belongs to Messaging and the SDK is able to display it to the end user
        if #available(iOS 14.0, *) {
            completionHandler([.banner, .sound, .badge])
        } else {
            completionHandler([.alert, .sound, .badge])
        }
    case .messagingShouldNotDisplay:
        // This push belongs to Messaging but it should not be displayed to the end user
        completionHandler([])
    case .notFromMessaging:
        // This push does not belong to Messaging
        // If you have push notifications in your app, place your code here

        // If not, just call the `completionHandler`
        completionHandler([])
    @unknown default: break
    }
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {

    id userInfo = notification.request.content.userInfo;

    // This checks whether a received push notification should be displayed by Messaging
    ZDKPushResponsibility shouldBeDisplayed = [ZDKPushNotifications shouldBeDisplayed:userInfo];

    switch (shouldBeDisplayed) {
        case ZDKPushResponsibilityMessagingShouldDisplay:
            // This push belongs to Messaging and the SDK is able to display it to the end user
            if (@available(iOS 14.0, *)) {
                completionHandler(UNNotificationPresentationOptionBanner | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
            } else {
                completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
            }
            break;
        case ZDKPushResponsibilityMessagingShouldNotDisplay:
            // This push belongs to Messaging but it should not be displayed to the end user
            completionHandler(UNNotificationPresentationOptionNone);
            break;
        case ZDKPushResponsibilityNotFromMessaging:
            // This push does not belong to Messaging
            // If you have push notifications in your app, place your code here

            // If not, just call the `completionHandler` and `break`
            completionHandler(UNNotificationPresentationOptionNone);
            break;
    }
}

Step 8 - Handle push notifications in your app

Implement userNotificationCenter(didReceive) to handle when the notification is tapped.

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo

    // This checks whether a received push notification should be handled by Messaging
    let shouldBeDisplayed = PushNotifications.shouldBeDisplayed(userInfo)

    switch shouldBeDisplayed {
    case .messagingShouldDisplay:
        // This push belongs to Messaging and the SDK is able to handle when the end user interacts with it
        PushNotifications.handleTap(userInfo) { viewController in
           // Handle displaying the returned viewController in here
        }
    case .messagingShouldNotDisplay:
        // This push belongs to Messaging but the interaction should not be handled by the SDK
        break
    case .notFromMessaging:
        // This push does not belong to Messaging
        // If you have push notifications in your app, place your code here

        // If not, just call `break`
        break
    @unknown default: break
    }

    completionHandler()
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
         withCompletionHandler:(void (^)(void))completionHandler {

    id userInfo = response.notification.request.content.userInfo;

    // This checks whether a received push notification should be handled by Messaging
    ZDKPushResponsibility shouldBeDisplayed = [ZDKPushNotifications shouldBeDisplayed:userInfo];

    switch (shouldBeDisplayed) {
        case ZDKPushResponsibilityMessagingShouldDisplay:
            // This push belongs to Messaging and the SDK is able to handle when the end user interacts with it
            [ZDKPushNotifications handleTap:userInfo completion:^(UIViewController * _Nullable viewController) {
                // Handle displaying the returned viewController in here
            }];
            break;
        case ZDKPushResponsibilityMessagingShouldNotDisplay:
            // This push belongs to Messaging but the interaction should not be handled by the SDK
            break;
        case ZDKPushResponsibilityNotFromMessaging:
            // This push does not belong to Messaging
            // If you have push notifications in your app, place your code here

            // If not, just call break
            break;
    }

    completionHandler();
}

Note: When the app is in a background state, the viewController returned will allow you to display the conversation. When the app is in a killed state however, it will return nil as the SDK is not initialised then.

If you want to change that behaviour, you will have to implement your own handling of the push display as well as handling the initialisation of the SDK and the handling of the messagingViewController.