Handling push notifications (Urban Airship)

Handling push notifications (Urban Airship)

You can 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 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, or change identities, 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.

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:

• Device registration
• Device unregistration
• Notification payload handling
• Ticket deep-linking

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

Device registration

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

Swift

// 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

NSLocale.preferredLanguages.first ?? "en"
ZDKPushProvider(zendesk: Zendesk.instance!).register(UAIdentifier: identifier, locale: locale) { (pushResponse, error) in
    print("Couldn't register device: \(identifier). Error: \(error)")
  } else {
    print("Successfully registered device: \(identifier)")
  }
}

Objective-C

...
NSString * locale = [[NSLocale preferredLanguages] firstObject];
[[[ZDKClassicPushProvider alloc] initWithZendesk:[ZDKClassicZendesk instance]] registerWithUAIdentifier:identifier locale:locale completion:^(NSString * _Nullable registrationResponse, NSError * _Nullable error) {
  if (error) {
    NSLog(@"Couldn't register device: %@. Error: %@ in %@", pushIdentifier, error, self.class);
  } else if (registrationResponse) {
    NSLog(@"Successfully registered device: %@ in %@", pushIdentifier, self.class);
  }
}];
...

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

ZDKPushProvider(zendesk: Zendesk.instance!).unregisterForPush()

Objective-C

[[[ZDKClassicPushProvider alloc] initWithZendesk:[ZDKClassicZendesk instance]] unregisterForPush];

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.

When a notification is received you can handle it using the Support-SDK's deep-linking feature or handle it yourself. If you choose to handle it yourself you can retrieve the ticket and fetch its comments using an API provider.

Ticket deep-linking

You can use the Support SDK's deep linking functionality to show the ticket directly in response to a notification tap.

Presenting the Request UI

Swift

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

//Inside a UIViewController
func presentRequest(with requestID: String) {
  let viewController = RequestUi.buildRequestUi(requestId: requestID)
  self.navigationController?.pushViewController(viewController, animated: true)
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    NSString * requestID = [[[[response notification] request] content] userInfo[@"tid"]];
}

//Inside a UIViewController
-(void) presentRequest:(NSString *)requestID {
    UIViewController * requestController = [ZDKRequestUi buildRequestUiWithRequestId:requestID];
    [self.navigationController pushViewController:requestController animated:YES];
}

Refresh comment stream

You can refresh the comment stream if it is visible. refreshRequest returns a boolean that indicates if the refresh was successful, e.g. the user had the ticket open at the time. If it returns false you will need to handle the notification yourself.

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
  let requestID = response.notification.request.content.userInfo["tid"]
  if Support.instance?.refreshRequest(requestId: requestID) {
    return
  } else {
    //Handle the notification
  }
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    NSString * requestID = [[[[response notification] request] content] userInfo[@"tid"]];
    if ([[ZDKSupport instance] refreshRequestWithRequestId:requestID]) {
        return;
    } else {
        // Handle push
    }
}

If you're only using the API providers and building the UI yourself:

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
  let requestID = response.notification.request.content.userInfo["tid"]
  if Support.instance?.refreshRequest(requestId: requestID) {
    return
  } else {
    //Handle the notification
  }
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    NSString * requestID = [[[[response notification] request] content] userInfo[@"tid"]];
    if ([[ZDKSupport instance] refreshRequestWithRequestId:requestID]) {
        return;
    } else {
        // Handle push
    }

}

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.