Android SDK

You can integrate the Connect SDK into your Android app to send user and event data to Zendesk Connect from the user's device. You can also use it to manage push notification tokens and perform other tasks.

The SDK supports Firebase Cloud Messaging (FCM) for push notifications.

The Android SDK supports Android API levels 19 to 28 (minSdkVersion 19 and targetSdkVersion 28).

This document covers the following topics:

See also the Connect SDK Javadoc.

Integrating the Connect Android SDK

Initial Setup
  1. Add the SDK to your project by including the following snippets in the app level build.gradle file:

    repositories {
        maven {
            url "https://zendesk.jfrog.io/zendesk/repo"
        }
    }
    ...
    dependencies {
        implementation group: "com.zendesk", name: "connect", version: "3.0.0"
    }
    

    For the latest version, see the SDK source code on GitHub.

  2. Create notification channels to display notifications.

    The Connect SDK needs a notification channel for each sound setting in the Connect dashboard for Android push campaign.

    For more information, see notification channels.

  3. Override the following string resources with the created channel IDs:

    <resources>
        <string name="connect_notification_channel_id">{YOUR_NOTIFICATION_CHANNEL_ID}</string>
        <string name="connect_silent_notification_channel_id">{YOUR_SILENT_NOTIFICATION_CHANNEL_ID}</string>
    </resources>
    
  4. Register the ConnectMessagingService in your AndroidManifest to allow the Connect SDK to receive push notifications from Firebase:

    <service android:name="com.zendesk.connect.ConnectMessagingService">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT"/>
        </intent-filter>
    </service>
    

    You can optionally replace some default values of this service to gain some control over the handling of the incoming push notifications. See Custom Services for more information.

  5. Register the ConnectActionService in your AndroidManifest to allow the Connect SDK to handle the incoming Intent from opened push notifications:

    <service android:name="com.zendesk.connect.ConnectActionService">
        <intent-filter>
            <action android:name="{YOUR_PACKAGE_NAME}.connect.action.OPEN_NOTIFICATION"/>
        </intent-filter>
    </service>
    

    You can optionally extend this service to gain some control over the handling of the Intent. See Custom Services for more information.

  6. Initialize Connect in the onCreate() method of an Application subclass. Use the application Context and the Connect API private key retrieved from the Connect dashboard to initialize the SDK:

    // Where `this` is an instance of `Application`
    Connect.INSTANCE.init(this, CONNECT_PRIVATE_KEY);
    

    For more information on the private key, see Authentication in the introduction.

    The notification channel is required for Android Oreo (8.0) and above and must be created before the Connect SDK is initialized.

    Here is an example of how to override the onCreate method:

    private static final String CONNECT_PRIVATE_KEY = "YOUR_CONNECT_PRIVATE_KEY";
    
    @Override
    public void onCreate() {
        super.onCreate();
    
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
            String notificationChannelId = getString(R.string.connect_notification_channel_id);
            String notificationChannelName = "YOUR_NOTIFICATION_CHANNEL_NAME"
    
            String silentNotificationChannelId = getString(R.string.connect_silent_notification_channel_id);
            String silentNotificationChannelName = "YOUR_SILENT_NOTIFICATION_CHANNEL_NAME"
    
            int importance = NotificationManager.IMPORTANCE_DEFAULT;
    
            NotificationChannel notificationChannel = new NotificationChannel(
                notificationChannelId,
                notificationChannelName,
                importance);
            notificationChannel.enableVibration(true);
    
            NotificationChannel silentNotificationChannel = new NotificationChannel(
                silentNotificationChannelId,
                silentNotificationChannelName,
                importance);
            silentNotificationChannel.setSound(null, null);
    
            NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            notificationManager.createNotificationChannel(notificationChannel);
            notificationManager.createNotificationChannel(silentNotificationChannel);
        }
    
        Connect.INSTANCE.init(this, CONNECT_PRIVATE_KEY);
    }
    

    More information about how to create Android notification channels can be found in the official Android documentation.

Customizing the SDK

Default Icon

The SDK has a default notification icon that's used if no Small Notif Icon is specified in the triggered campaign. The default is just a white square and can be overridden by creating a notification icon drawable called ic_connect_notification_icon.

Custom Services

You can replace the following default values of ConnectMessagingService to allow additional control when notifications are received:

  • MessageReceiver
  • NotificationEventListener
  • NotificationFactory

You can override ConnectActionService to allow additional control when notifications are opened.

Providing a MessageReceiver

To listen for usual callbacks of the FirebaseMessagingService, provide an implementation of MessageReceiver to Connect through a static method. Connect will invoke those methods every time they are called by Firebase.

Create your own implementation of the MessageReceiver:

public class SampleMessageReceiver implements MessageReceiver {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage, Service service) {
        // Perform custom logic when a message is received
    }

    @Override
    public void onDeletedMessages(Service service) {
        // Perform custom logic when a message is deleted
    }

    @Override
    public void onMessageSent(String messageId, Service service) {
        // Perform custom logic when a message is sent
    }

    @Override
    public void onSendError(String messageId, Exception exception, Service service) {
        // Perform custom logic when a send error occurs
    }

    @Override
    public void onNewToken(String token, Service service) {
        // Perform custom logic when a new token is received
    }

}

Set your own implementation of MessageReceiver to Connect:

ConnectMessagingService.setMessageReceiver(new SampleMessageReceiver());
Providing a NotificationEventListener

To listen for callbacks of when a Notification is received, provide an implementation of NotificationEventListener to Connect through a static method.

Create your own implementation of the NotificationEventListener:

public class SampleNotificationEventListener implements NotificationEventListener {

    @Override
    public void onNotificationReceived(SystemPushPayload payload) {
        // Perform custom logic when a notification is received
    }

    @Override
    public void onNotificationDisplayed(SystemPushPayload payload) {
        // Perform custom logic when a notification is displayed
    }

}

See the Javadoc for more information about the SystemPushPayload.

Set your own implementation of NotificationEventListener to Connect:

ConnectMessagingService.setNotificationEventListener(new SampleNotificationEventListener());
Providing a NotificationFactory

To provide your own custom Notification when a message needs to be displayed, provide an implementation of NotificationFactory to Connect through a static method.

You must set the channel id when providing a custom Notification. Otherwise the Notification might not be displayed correctly.

Create your own implementation of the NotificationFactory:

public class SampleNotificationFactory implements NotificationFactory {

    @Override
    public Notification create(SystemPushPayload payload) {
        String channelId = "{YOUR_NOTIFICATION_CHANNEL_ID}"

        NotificationCompat.Builder builder = new NotificationCompat.Builder(context, channelId);

        // Perform custom logic to build the notification

        // Return the notification to be displayed by Connect
        return builder.build();
    }

}

See the Javadoc for more information about the SystemPushPayload.

Set your own implementation of NotificationFactory to Connect:

ConnectMessagingService.setNotificationFactory(new SampleNotificationFactory());
Customizing the ConnectActionService

By default, the ConnectActionService attempts to open a deep link if it is available in the notification payload, or open the host app launch activity if none was provided. There are static methods that you can use to modify the behaviour of this service. You should set the behavior when you are initializing the SDK.

To disable deep link handling:

// This is true by default
ConnectActionService.shouldHandleDeepLinks(false);

To disable opening the launch activity:

// This is true by default
ConnectActionService.shouldOpenLaunchActivityByDefault(false);

Here's an example of how to override the action service:

public class SampleActionService extends ConnectActionService {

    @Override
    public void onOpenNotification(SystemPushPayload payload) {
        // Perform custom logic when a notification is opened
    }
}

See the Javadoc for more information about the SystemPushPayload.

After overriding the action service, register your service in the AndroidManifest.xml:

<service android:name=".SampleActionService">
    <intent-filter>
        <action android:name="{YOUR_PACKAGE_NAME}.connect.action.OPEN_NOTIFICATION"/>
    </intent-filter>
</service>
Notification Channels

Connect needs notification channels to allow notifications to be displayed on Android Oreo (8.0) and above.

A separate channel is required for each sound setting offered by the Connect dashboard:

  • default -> connect_notification_channel_id
  • silent -> connect_silent_notification_channel_id

The default channel should play the system default message tone, or a custom tone if desired. The silent channel should be unobtrusive and play no sound.

Using the SDK

Identify User

Use the identifyUser() method to send user data to Connect. The SDK provides a UserBuilder class to create User objects. The method takes the following argument:

  • a User object containing the user attributes

See the Javadoc for more information.

User user = new UserBuilder("example_user_id")
           .setFirstName("John")
           .setLastName("Doe")
           .setEmail("[email protected]")
           .setPhoneNumber("415-555-1234")
           .build();

Connect.INSTANCE.identifyUser(user);

For more information, see Users.

Alias User

The SDK automatically attempts to alias a new user with the currently active user. This means that both users IDs will reference the same user in Connect. To prevent two unique users from being aliased with each other, you must call logoutUser() before calling identifyUser() for the second user.

Track Event

Use the trackEvent() method to send event data to Connect. The SDK provides an EventFactory class with methods to create Event objects. The method takes the following argument:

  • an Event object containing the event name and properties

See the Javadoc for more information.

Map<String, Object> properties = new HashMap<>();
Event event = EventFactory.createEvent("event_name", properties);
Connect.INSTANCE.trackEvent(event);

For more information, see:

Register for Push

Use the registerForPush() method to send push notifications to the user's device. Identifying a user using identifyUser() will automatically enable push notifications for the user's device.

Connect.INSTANCE.registerForPush();

See the Javadoc for more information.

Disable Push

Use the disablePush() method if you no longer want to send push notifications to the user's device.

Connect.INSTANCE.disablePush();

See the Javadoc for more information.

Logout

Use the logoutUser() method to clear user data from the device and disable the FCM device token with Connect.

Connect.INSTANCE.logoutUser();

See the Javadoc for more information.

Get User

Use the getUser() to retrieve details about the currently active user.

User user = Connect.INSTANCE.getUser();

See the Javadoc for more information.

Deep Linking

To use the deep linking capabilities in Connect push notifications, you must set up your app to handle links. To do so, add an <intent-filter> to each of your activities you want to be linkable. For more information, see Add Intent Filters for Your Deep Links in the Android Developers documentation.

Debugging Your Integration

You can enable logging to help debug issues with your integration. Add the following line of code to your app before you initialize the Connect SDK.

Logger.setLoggable(true);

When that's in place, recreate the issue and check the console log for errors. This is usually enough to troubleshoot most integration issues.

Proguard

All of the necessary Proguard rules have been included in the SDK consumer-proguard.pro and will be applied automatically when Proguard is enabled.