Handling 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.
  • If a device token becomes invalid, you will need to register the new device token for push notifications to continue being 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 four 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 Support about unregistered devices
Account Configuration

In the Zendesk Support 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 token (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 Android Guide.

You can also check out our sample application to see a working Support SDK application with the Urban Airship SDK integrated onto it.

Application Integration

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

Device registration

You must register devices interested in receiving push notifications with Zendesk Support.

You need an Urban Airship channel id to register devices. See Urban Airship SDK Integration above if you don't have one yet.

To register the device, send the channel id to your Zendesk Support instance through the Support SDK API as follows:

Zendesk.INSTANCE.provider().pushRegistrationProvider().registerWithUAChannelId("<channel id>", new ZendeskCallback<String>() {
    @Override
    public void onSuccess(String result) {

    }

    @Override
    public void onError(ErrorResponse errorResponse) {

    }
});
Device unregistration

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

Zendesk.INSTANCE.provider().pushRegistrationProvider().unregisterDevice(new ZendeskCallback<Void>() {
    @Override
    public void onSuccess(final Void response) {

    }

    @Override
    public void onError(ErrorResponse errorResponse) {

    }
});
Notification payload handling

To access the pushed payload set up a BaseIntentReceiver.

The id of the updated ticket can be extracted from the provided PushMessage by calling:

@Override
protected boolean onNotificationOpened(Context context, PushMessage message, int notificationId) {
    ...
    String ticketId = message.getPushBundle().getString("tid");
    ...
}

When a notification is received you have the option of using the Support SDK's deep-linking feature to handle the notification or handling it yourself. If you choose to handle it yourself, you can retrieve the ticket and fetch its comments using an API provider. See the following topics in the Support SDK JavaDocs:

Ticket deep-linking

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

Acquire an Intent

Use the RequestUiConfig builder to get a deep-link Intent for your notification's content Intent. Use one of the methods provided by ZendeskDeepLinking.INSTANCE to get an Intent.

final Intent mainActivity = new Intent(getApplicationContext(), MainActivity.class);
mainActivity.putExtra(MainActivity.EXTRA_VIEWPAGER_POSITION, MainActivity.VIEWPAGER_POS_HELP);

final ArrayList<Intent> backStackItems = new ArrayList<>();
backStackItems.add(mainActivity);

final Intent deepLinkIntent = new RequestUiConfig.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);

To preserve the navigation flow, you can specify a list of back stack intents. These activities will be shown if the user presses back. Ensure that provided Intents are explicit Intents.

Using the Intent

The returned Intent invokes a BroadcastReceiver that handles the further deep linking process.

1. Notifications

final Intent deepLinkIntent = new RequestUiConfig.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);

final PendingIntent contentIntent = PendingIntent.getBroadcast(
    context, {requestCode}, deepLinkIntent, {flags}
);

final Notification notification = new NotificationCompat.Builder(context)
    ...
    .setContentIntent(contentIntent)
    ...
    .build();

2. In an Activity/Fragment

final Intent deepLinkIntent = new RequestUiConfig.Builder()
    .withRequestId(requestId)
    .deepLinkIntent(getApplicationContext(), backStackItems);
context.sendBroadcast(deepLinkIntent);
Refresh comment stream

Another feature provided by Support.INSTANCE is the possibility of refreshing the comment stream if it's visible.

/**
 *
 * ...
 *
 * @param requestId the ID of the request to refresh
 * @param context the application Context
 * @return true if the conversation UI was refreshed on screen, false if not.
 */
public boolean refreshRequest(String requestId, Context context) {

Example:

if (Support.INSTANCE.refreshRequest(requestId, getApplicationContext())) {
    return;
} else {
    //e.g. show a notification
}

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.