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: "2.1.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 extend 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"
            int importance = NotificationManager.IMPORTANCE_DEFAULT;
    
            NotificationChannel notificationChannel = new NotificationChannel(
                notificationChannelId,
                notificationChannelName,
                importance);
            notificationChannel.enableVibration(true);
    
            NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            notificationManager.createNotificationChannel(notificationChannel);
        }
    
        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.png.

Custom Services

The following services can be overridden to allow additional control when notifications are received and opened:

  • ConnectMessagingService
  • ConnectActionService
Customizing ConnectMessagingService

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

public class SampleMessagingService extends ConnectMessagingService {

    @Override
    public void handleNonConnectNotification(RemoteMessage message) {
        // Perform logic to handle notifications from sources outside of Connect
    }

    @Override
    public void onNotificationReceived(NotificationPayload payload) {
        // Perform custom logic when the notification has been received
    }

    @Override
    public void onNotificationDisplayed(NotificationPayload payload) {
        // Perform custom logic when the notification has been displayed
    }

    @Override
    public Notification provideCustomNotification(NotificationPayload payload) {
        Notification customNotification;
        // Create custom notification
        return customNotification;
    }
}

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

<service android:name=".SampleMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>
Customizing 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: java // This is true by default ConnectActionService.shouldHandleDeepLinks(false); To disable opening the launch activity: java // 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(NotificationPayload payload) {
        // Perform custom logic when a notification is opened
    }
}

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("john@example.com")
           .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.