Handle push notifications (Urban Airship)

This feature is only available on the Team, Professional, and Enterprise plans.

This page shows you how to use push notifications with the Support SDK using Urban Airship.

The Zendesk Support SDK can be set up to notify the end user when an agent posts a public comment on their request.

Before you start

Before you start, the following information is useful to know:

  • You can use either the Webhook API or Urban Airship to send push notifications.
  • If you already have a push notifications service we recommend you to use the Webhook API option. On the other side, if you don't have your own push notifications service or you are not willing to develop one, you should use the Urban Airship alternative.
  • You will only receive notifications on requests that were created through the Support SDK.
  • The configuration of your app in Zendesk Support must include the push notification details for your chosen option.
  • If you switch from one integration to another, register the devices again. Otherwise the push notifications will not be delivered properly.

Use Urban Airship for push notifications

Zendesk Support notifies Urban Airship when a notification needs to be sent.

For a full Urban Airship integration, you need to do three things:

  1. Configure your Support SDK App in your account
  2. Integrate the Urban Airship SDK into your app
  3. Set up your app to handle the push notification and ticket deep-linking
  4. Notify Zendesk about unregistered devices
Account Configuration

In the Zendesk admin interface, select the Urban Airship option in the push notifications combo box in the Customization tab of the Mobile SDK page.

Two text fields are displayed for Urban Airship credentials. The second one, Urban Airship App Master Secret, is particularly important. Make sure you use your Urban Airship master key. If you use the Urban Airship app key, push notifications won't be sent.

Push Notifications Urban Airship Configuration

Urban Airship SDK Integration

Integrating the Urban Airship SDK is the only way of obtaining an Urban Airship device identifier (a channel id in Urban Airship parlance). Once you have the channel id, you can register the device as described in Application Integration below.

The setup is described in detail in the Urban Airship iOS Guide.

You can also check out our sample application to see a working Support SDK application that integrates the Urban Airship SDK.

Application Integration

You need to handle the following four scenarios in the app code:

You must also enable Background fetch and Remote notifications in the Background Modes section of your apps Capabilities in your project configuration.

Push Notifications Setup Background Modes

Device registration

First, you need to ask the user for permission, as per the iOS docs.

Swift 3

// Register the app for remote notifications in application:didFinishLaunchingWithOptions:
UAirship.push().userPushNotificationsEnabled = true

Objective-C

// Register the app for remote notifications in application:didFinishLaunchingWithOptions:
[UAirship push].userPushNotificationsEnabled = YES;

This should result in a call to the app delegates didRegisterForRemoteNotificationsWithDeviceToken method. You need an Urban Airship channel id to register devices. See Urban Airship SDK Integration above if you don't have one yet. After obtaining the Urban Airship channel id you can use it to register the device:

Swift 3

ZDKConfig.instance().enablePush(withUAChannelID: identifier) { pushResponse, error in
  if let error = error {
    print("Couldn't register device: \(identifier). Error: \(error)")
  } else {
    print("Successfully registered device: \(identifier)")
  }
}

Objective-C

...
[[ZDKConfig instance] enablePushWithUAChannelID:identifier callback:^(ZDKPushRegistrationResponse *registrationResponse, NSError *error) {
    if (error) {
        [ZDKLogger log:@"Couldn't register device: %@. Error: %@", identifier, error];
    } else if (registrationResponse) {
        [ZDKLogger log:@"Successfully registered device: %@", identifier];
    }
}];
...

Note: We have a category on NSData which parses the identifier returned in the above delegate method. Feel free to use this method from our sample app, NSData+ZDKSampleApp.m.

To register for push notifications with Zendesk Support, a valid identity must be set in the Support SDK. Depending on how your app is configured, you probably won't have an identity ready in the AppDelegate. We suggest you store the device identifier returned by Apple and register for push notifications with Zendesk Support once an identity becomes available, such as when the user signs into your app.

Device unregistration

When the user signs out or doesn't want push notifications anymore, call the following API to remove the device identifier from Zendesk Support:

Swift 3

ZDKConfig.instance().disablePush(identifier) { status, error in
  if let error = error {
    print("Couldn't unregistered device: \(identifier). Error: \(error)")
  } else {
    print("Successfully unregistered device: \(identifier)")
  }
}

Objective-C

[[ZDKConfig instance] disablePush:identifier callback:^(NSNumber *responseCode, NSError *error) {
    if (error) {
        [ZDKLogger log:@"Couldn't unregister device: %@. Error: %@", identifier, error];
    } else if (responseCode) {
        [ZDKLogger log:@"Successfully unregistered device: %@", identifier];
    }
}];
Notification payload handling

Set up the delegate methods to handle the payload received as described in the iOS Notification Programming Guide on the Apple site.

Swift 3

func application(application: UIApplication, didReceiveRemoteNotification
  userInfo: [NSObject : AnyObject], fetchCompletionHandler
  completionHandler: (UIBackgroundFetchResult) -> Void) {

  var pushUtilUserInfo = userInfo
  pushUtilUserInfo["zendesk_sdk_request_id"] = userInfo["tid"]

  ZDKPushUtil.handlePush(
    pushUtilUserInfo,
    for: application,
    presentationStyle: .formSheet,
    layoutGuide: ZDKLayoutRespectTop,
    withAppId: "<your-app-id>",
    zendeskUrl: "<your-zendesk-url>",
    clientId: "<your-client-id>")
}

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
 {
  ...
    [ZDKPushUtil handlePush:userInfo
             forApplication:application
          presentationStyle:UIModalPresentationFormSheet
                layoutGuide:ZDKLayoutRespectTop
                  withAppId:<your-app-id>
                 zendeskUrl:<your-zendesk-url>
                   clientId:<your-client-id>
     fetchCompletionHandler:completionHandler];
    ....
}
Ticket deep-linking

You can use the Support SDK's deep linking functionality to show the ticket in a direct way in response to a notification tap. We implemented a push handler that takes the userInfo dictionary from the application:didReceiveRemoteNotification:fetchCompletionHandler:. The handler attempts to do one of three things depending on the state of the application:

  • If the app is currently on the request for which a push was received, the push handler refreshes the comment stream
  • If the app is on the request list view, the push handler displays an alert giving the user the option to view the update. The user can ignore or open the request, in which case the handler pushes a comments view on the view stack
  • If the app is on any other screen, the push handler displays an alert giving the user the option to view the update. The user can ignore or open the request, in which case the handler presents a comments view modally

To handle instances when your app is not running and a push notification is received, the push handler requires parameters from the init method. If required, these parameters are used to init the Support SDK.

Bulk Device Deletion

Urban Airship has a Feedback API which returns a list of tokens that can’t receive push notifications because the application has been uninstalled. You need to let us know too.

You can use the bulk unregistering endpoint for push notification devices Bulk Unregister API to unregister the devices of customers that deleted the app or are no longer registered.