Handle push notifications (Urban Airship)

This is the developer guide for the Support SDK v1 for Android. For Support SDK v2, see Support SDK v2 Android.

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 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 Airhip 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:

ZendeskConfig.INSTANCE.enablePushWithUAChannelId("<channel id>", new ZendeskCallback<PushRegistrationResponse>() {
    @Override
    public void onSuccess(PushRegistrationResponse pushRegistrationResponse) {

    }

    @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:

ZendeskConfig.INSTANCE.disablePush("<channel id>", new ZendeskCallback<Response>() {
    @Override
    public void onSuccess(Response 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.

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 one of the methods provided by ZendeskDeepLinking.INSTANCE to get an Intent.

/**
 * Get an pre-configured {@linkplain android.content.Intent} to open a request.
 *
 * @param context               An application context
 * @param requestId             A valid requestId
 * @param subject               A subject
 * @param backStackActivities   A list of back stack activities
 * @param fallbackActivity      An activity that will be shown, if something fails (e.g. user configuration changed)
 * @return                      An intent
 */
@Nullable
public Intent getRequestIntent(
    Context context,
    String requestId,
    @Nullable String subject,
    @Nullable ArrayList<Intent> backStackActivites,
    @Nullable Intent fallbackActivity
);

/**
 * Get an pre-configured {@link Intent} to open a request.
 *
 * @param context               An application context
 * @param requestId             A valid requestId
 * @param subject               A subject
 * @param backStackActivities   A list of back stack activities
 * @param fallbackActivity      An activity that will be shown, if something fails (e.g. user configuration changed)
 * @param zendeskUrl            The full URL of your Zendesk Support instance, https://{subdomain}.zendesk.com
 * @param applicationId         The application id of your SDK app, as found in the web interface
 * @param oauthClientId         The oauth client id that was supplied when you set up oauth in the
 *                              web interface
 * @return                      An intent
 */
public Intent getRequestIntent(
    Context context,
    String requestId,
    @Nullable String subject,
    @Nullable ArrayList<Intent> backStackActivities,
    @Nullable Intent fallbackActivity,
    String zendeskUrl,
    String applicationId,
    String oauthClientId
);

It's important to make sure that ZendeskConfig is initialized. If it isn't, getRequestIntent() will return null. If you want to use deep linking in an IntentReceiver or BroadcastReceiver, keep in mind that your ZendeskConfig could be uninitialized even if you've initialized it in an Activity or Fragment before.

Do the following to prevent the Intent from being null:

  1. Initialize ZendeskConfig before acquiring an Intent.
  2. Use the overloaded method getRequestIntent(), which accepts a Zendesk Support URL, application ID, and oAuth client ID.

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

Important: Due to limitations of TaskStackBuilder, the provided list of back stack activities won’t be shown on devices running Android 2.3 and below.

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 = ZendeskDeepLinking.INSTANCE.getRequestIntent(
    context, "{requestId}", "{subject}", backStackItems, mainActivity
);
Using the Intent

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

1. Notifications

final Intent deepLinkIntent = ZendeskDeepLinking.INSTANCE.getRequestIntent(
    context, "{requestId}", "{subject}", backStackItems, mainActivity
);

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 = ZendeskDeepLinking.INSTANCE.getRequestIntent(
    context, "{requestId}", "{subject}", backStackItems, mainActivity
);
context.sendBroadcast(deepLinkIntent);
Refresh comment stream

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

/**
 * Will reload comments in a {@linkplain com.zendesk.sdk.requests.ViewRequestFragment}
 * if it's visible to the user and displaying the given requestId.
 *
 * @param requestId         A request id
 * @return                  True if a reload was triggered, false if not.
 */
public boolean refreshComments(String requestId);

Example:

final boolean commentsRefreshed = ZendeskDeepLinking.INSTANCE.refreshComments(requestId);
if(!commentsRefreshed){
    //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.