Getting Started

Getting Started

Add Messaging to your project to engage with your users from your Android app.

Prerequisites

Before starting the integration of the Zendesk SDK, please ensure that the following prerequisites are fulfilled.

Ensure you meet the minimum supported Android API level

• Minimum API level (minSdkVersion) for the Zendesk SDK is 21.

  You might get the following warning.

  Dependency 'androidx.appcompat:appcompat-resources:1.5.1' requires libraries and applications that depend on it to compile against version 32 or later of the Android APIs.

  This does not prevent you from compiling. You can still target Zendesk SDK version 21 and compile with version 32 or later.

• Minimum Java version required to run the Zendesk SDK is 8. Below is an example of how to configure your project to compile with Java version 8, using the following compile options added to your build.gradle module:

  android {
      compileOptions {
          sourceCompatibility = JavaVersion.VERSION_1_8
          targetCompatibility = JavaVersion.VERSION_1_8
      }
  }

Obtain a channel key from Zendesk's Admin Center

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Add the SDK dependencies

You can add the Android SDK to your project using Maven.

The following permissions are automatically added to your AndroidManifest because the SDK has to make network requests to work as expected.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

1. Add the Zendesk Maven repository to your project dependency.

   repositories {
       maven {
           url "https://zendesk.jfrog.io/artifactory/repo"
       }
   }

2. Add the following dependency to your app's build.gradle:

   implementation "zendesk.messaging:messaging-android:latest_version"

   Replace latest_version with the latest available version number from the Release Notes.

Obtain the channel key

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Initialize the SDK

Initialize the SDK in the onCreate method of your Application class. To do this, you'll need your channel key, which you can find in the Zendesk Admin Center. If you don't have admin access to Zendesk, ask a Zendesk admin to get the information for you.

The snippets below give an example of a Messaging initialization in both Kotlin and Java.

Kotlin

import android.app.Application
import android.util.Log
import zendesk.android.Zendesk
import zendesk.messaging.android.DefaultMessagingFactory

/**
 * A sample [Application] with a [DefaultMessagingFactory] integration in Kotlin.
 */
class Sample : Application() {

    override fun onCreate() {
        super.onCreate()
        Zendesk.initialize(
            context = this,
            channelKey = /*"{channel_key}"*/,
            successCallback = { zendesk ->
                Log.i("IntegrationApplication", "Initialization successful")
            },
            failureCallback = { error ->
                // Tracking the cause of exceptions in your crash reporting dashboard will help to triage any unexpected failures in production
                Log.e("IntegrationApplication", "Initialization failed", error)
            },
            messagingFactory = DefaultMessagingFactory()
        )
    }

}

Java

import android.app.Application;
import android.util.Log;
import zendesk.android.Zendesk;
import zendesk.messaging.android.DefaultMessagingFactory;

/** A sample {@link Application} with a {@link DefaultMessagingFactory} integration in Java. */
class JavaIntegrationApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        Zendesk.initialize(
                this,
                /*"{channel_key}"*/,
                zendesk -> Log.i("IntegrationApplication", "Initialization successful"),
                error -> Log.e("IntegrationApplication", "Messaging failed to initialize", error),
                new DefaultMessagingFactory());
    }
}

Show the conversation

If Zendesk.initialize() is successful, you can use the code snippets below anywhere in your app to show the conversation screen.

If Zendesk.initialize() is not successful, a stub implementation of the Zendesk class is returned that logs to the console.

Kotlin

Zendesk.instance.messaging.showMessaging(context)

Java

Zendesk.getInstance().getMessaging().showMessaging(context);

Demo App

We provide our users multiple demo apps to showcase our SDK's functionalities.

Each app showcases one specific feature, including basic implementation, JWT authentication, and more. Each app contains a README file detailing the step required to make the app work.

You can find them in our Zendesk SDK Demo app github.

Next Steps

If you have completed the steps above, you are now in good shape to explore the SDK and understand how messaging will work for your business and your end users.

Push Notifications

To ensure a good end-user experience, we also recommend setting up push notifications to work correctly with your app. The steps required to set it up are outlined in Push notifications.

Unread Messages

When the user receives a new message, an event is triggered with the updated total number of unread messages. To subscribe to this event, add an event listener to your Zendesk SDK instance. See Events for the necessary steps to observe unread messages.

In addition, you can retrieve the current total number of unread messages by calling getUnreadMessageCount() on Messaging on your Zendesk SDK instance.

You can find a demo app showcasing this feature in our Zendesk SDK Demo app github.

Kotlin

zendesk.messaging.getUnreadMessageCount()

Java

zendesk.getMessaging().getUnreadMessageCount();

Advanced Integration

To explore more advanced integration options, see Advanced integration.

Troubleshooting

We recommend tracking the cause of any initialization failures in your crash reporting dashboard. This will help in troubleshooting your integration once deployed in production.

Logging

Logging is disabled by default. You can enable it by using the following in either Java or Kotlin:

import zendesk.logger.Logger;

Logger.setLoggable(true);

You can check the state of the Logger by using:

Logger.isLoggable();