Quick start - Support SDK for Android

This hands-on tutorial shows you how to build a functioning Android application in 30 minutes that lets users access your help center directly from the mobile app. The app also lets users submit support requests to your agents in Zendesk Support.

The tutorial uses the Support SDK for Android, a shared code library that lets you easily incorporate different Zendesk customer support features in Android applications. Zendesk has other options for providing customer service in mobile apps:

• You can use the Chat SDK to let users chat with support agents. To learn how, see Quick start - Chat SDK for Android.

• You can use the Unified SDK to incorporate Zendesk bots with Support to create a unified messaging experience.

You need Android Studio to build the small Android application in this tutorial. You can download Android Studio from the Android developer website.

You'll also need a Zendesk Support account or a trial account. You can request a sponsored test account that doesn't expire after 14 days like the trial account.

Make sure your help center is enabled in your Zendesk Support account. See Getting started with Guide in Zendesk help.

Though this quick start guide provides step-by-step instructions to build a simple application, it's not an Android app tutorial. If you're new to Android development, I highly recommend working through the lessons in Building Your First App on the Android website.

The guide walks you through the following basic steps for adding Zendesk customer support features to an Android application:

1. Creating a sample project
2. Adding the Support SDK to the project
3. Initializing the Support SDK
4. Creating a button to launch the help center
5. Adding an event listener for the Help button
6. Testing the integration
7. Next steps

The tutorial uses version 5.1.1 of the Support SDK. It was tested using Android Studio 2021.3.1 (Dolphin).

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk can't provide support for third-party technologies such as Java, Android, and Android Studio. Please post any issue in the Zendesk SDKs community, or search for a solution online.

Creating a sample project

This section shows you how to create a quick sample project in Android Studio. You'll use the project to try out the Support SDK.

1. In Android Studio, select File > New > New Project.

   If you're on the welcome window, click Next and follow the instructions to set your installation type and UI theme (light or dark.)

2. In the New Project screen, make sure the Phone and Tablet tab is selected, click Empty Activity, and click Next.

   

3. Set the following options for the project:

   • Name - Enter My Sample App or something similar
   • Package name - (required) Enter something like com.sample.mysampleapp
   • Save location - (required) Choose where you want to save the project
   • Language - Java
   • Minimum SDK - API 21: Android 5.0 (Lollipop)
   • Use legacy android.support libraries - Leave unchecked

4. Click Finish.

Android Studio creates all the files and basic settings for your project. You can view the files in the Project navigator on the left side of the screen. If you don't see the files, click the first icon (the folder icon) on the upper side of the panel.

Adding the Support SDK to the project

1. In your project files in the left sidebar, locate Gradle Scripts > build.gradle (Module: app), then double-click the file to open it in the editor. In my case, the file is build.gradle (Module: My_Sample_App.app).

   

   Note: Make sure not to open the first gradle file, which in my case is build.gradle (Project: My_Sample_App).

2. Before the dependencies section, add the following repositories section:

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

3. In the dependencies section, insert the following line (highlighted):

   dependencies {
       implementation group: 'com.zendesk', name: 'support', version: '5.3.0'
   }

   The build.gradle file should look partially as follows:

   repositories {
       maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
   }
   
   dependencies {
       implementation group: 'com.zendesk', name: 'support', version: '5.3.0'
   }

4. Save the file, then integrate the Support SDK in the project by selecting File > Sync Project with Gradle Files.

If you see the following error, you'll need to update your settings.gradle file as follows.

Build was configured to prefer settings repositories over project 
repositories but repository 'maven' was added by build 
file 'app/build.gradle'.

1. In your project files in the left sidebar, locate Gradle Scripts > settings.gradle, then double-click the file to open it in the editor.

2. Replace repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) with repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS).

3. In the repositories section, insert the following line (highlighted):

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

   The settings.gradle file should look partially as follows:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
           google()
           mavenCentral()
        }
    }

4. Save the file, then integrate the Support SDK in the project by selecting File > Sync Project with Gradle Files.

   You can ignore the deprecated Gradle warning.

Running a test build

Before going any further, make sure you successfully added the Support SDK to your project. One way is to run a test build in a phone emulator. The application doesn't do much yet, but if you don't get any build errors you know you're on the right path. You might get some build warnings but you can ignore them for now.

You can use the emulator that’s included in Android Studio. First, you'll need to create an Android Virtual Device (AVD) definition for the emulator. Your AVD definition will specify the characteristics of an Android phone. In this case, you'll define a Pixel phone.

1. Click the Device Manager icon on the toolbar (or select Tools > Device Manager).

2. In the Virtual Devices screen, click Create device.

3. In the Select Hardware screen, select the latest, regular-sized Pixel phone, and then click Next.

4. In the System Image screen, click the Download link next to the latest recommended system image (Android API 32 with x86-64 ABI at the time of this writing).

5. After the download is complete, select the system image from the list and click Next.

6. On the next screen, change the AVD Name to something like "Pixel phone", keep the default values of the remaining options, then click Finish.

7. In the Device Manager screen, click the right-pointing triangle on the right side to launch this phone in the emulator:

   

   Be patient. It can take a while to get going the first time it starts.

8. Once the emulator is up and running, return to your Project window, click the Run icon (green triangle) on the toolbar (or select Run > Run 'app'), and select your Pixel phone.

   

   Eventually your sample app should open in the Pixel phone emulator:

   

Consider the test a success if you don't get any build errors.

Initializing the Support SDK

Before a user can use a Zendesk customer support feature on their device, the application has to create and prepare an instance of the Support framework. The initialization process involves setting initial values and performing other setup tasks.

In this section, you'll update the sample application to initialize the Support SDK dependencies and make it ready for use. The task consists of the following steps:

1. Getting the initialization code from your Zendesk Support account
2. Adding the initialization code to your application
3. Adding a user identity

Getting the initialization code from your Zendesk Support account

You get the initialization code from your Zendesk Support admin interface. The code is generated when an Zendesk Support admin registers a mobile app in Zendesk Support.

You'll need to sign in as a Zendesk Support admin, or ask an admin to complete the following steps for you.

1. In Admin Center, click the Channels icon () in the sidebar, then select Classic > Mobile SDK.

   If you have not already done so, check the subscription and license agreement checkbox and click Get Started.

2. Click Add app.

3. In the Setup tab, enter a name for your app.

   The name is for your reference only and is not shown to your users.

4. Copy and save the Android code snippet.

   The initialization code is unique to your app and your instance of Zendesk Support. Save the code in a text file for now.

   

5. For Authentication method, select Anonymous.

   When the application accesses Zendesk Support, it needs to be able to authenticate as a user. You can use anonymous access or JWT authentication. For simplicity, you'll use anonymous access for the sample app.

6. Click Save.

Adding the initialization code to your application

Android applications are event driven, so you need to initialize the SDK in an event handler. By default, your application comes with an onCreate(Bundle) event handler that runs when an instance of your MainActivity subclass is created. You can add your own code to this event handler.

1. Make sure the MainActivity.java file is open in the Android Studio editor. It should be open in an editor tab by default. If not, you'll find the file in app/java/com.sample.mysampleapp in the Project panel on the left.

2. Add the initialization code you copied from Zendesk Support earlier to the onCreate(Bundle) event handler. The updated handler should look as follows with the initialization code (highlighted):

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       Zendesk.INSTANCE.init(context, "https://omniwear.zendesk.com",
           "23705744c16d8e0698b45920f18aa26e43d7",
           "mobile_sdk_client_b7fd695c0e9a6056");
   
       Support.INSTANCE.init(Zendesk.INSTANCE);
   }

   Zendesk, Support, and context should turn red, indicating undefined symbols. You'll fix this next.

3. Replace context with the string this (no quotes).

4. To fix the Zendesk and Support errors, click anywhere in the red text, then press Option+Enter (Mac) or Alt+Enter (Windows) to launch the project quick fix feature. Select Import Class if prompted. Android Studio automatically adds the missing import statements at the top of the file:

   import zendesk.core.Zendesk;
   import zendesk.support.Support;

   The text color should return to normal.

   If you prefer, you can insert the import statements above manually.

5. Run a build to make sure you don't get any error messages.

Adding a user identity

When the application accesses Zendesk Support, it needs to be able to authenticate as a user. You can use anonymous access or JWT authentication. For simplicity's sake, you selected anonymous access when you registered your app in Zendesk Support above.

1. Add the following code (highlighted) after the Zendesk.INSTANCE.init(...) statement but before the Support.INSTANCE.INIT(...) statement:

   Identity identity = new AnonymousIdentity();
   Zendesk.INSTANCE.setIdentity(identity);
   
   Support.INSTANCE.init(Zendesk.INSTANCE);

   Some parts of the code should turn red again, indicating the symbols are undefinined. Project quick fix can define these for you, as follows.

2. To fix the errors indicated by the red strings, click anywhere in a red string, press Option+Enter (Mac) or Alt+Enter (Windows), and select Import Class if prompted. Repeat for each red string until the text color returns to normal.

   Project quick fix should have added the following two import statements:

   import zendesk.core.AnonymousIdentity;
   import zendesk.core.Identity;

   The completed onCreate(Bundle) handler should look as follows:

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       Zendesk.INSTANCE.init(this, "https://omniwear.zendesk.com",
               "23705744c16d8e0698b45920f18aa26e43d7",
               "mobile_sdk_client_b7fd695c0e9a6056");
   
       Identity identity = new AnonymousIdentity();
       Zendesk.INSTANCE.setIdentity(identity);
   
       Support.INSTANCE.init(Zendesk.INSTANCE);
   }

   You should also have four new import statements at the top of the file:

   import zendesk.core.AnonymousIdentity;
   import zendesk.core.Identity;
   import zendesk.core.Zendesk;
   import zendesk.support.Support;

3. Save then run a build to make sure you don't get any error messages.

If everything checks out, you can start adding support features to your application.

Creating a button to launch the help center

The help center feature in the Support SDK is designed to open in response to an event such as a button tap.

Your default sample project consists of a ConstraintLayout containing a TextView that displays "Hello World!". The application's layout is defined in the activity_main.xml file in the res/layout folder:

If the Design view is displayed, click the Code button in the upper-right corner of the editor window.

You'll change the layout to a vertical LinearLayout containing a single Help button.

1. In the Project window, make sure the activity_main.xml file is open in the editor. If not, you'll find the file in the res/layout folder in the Project panel.

2. Replace all the contents of the file with the following layout code:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:gravity="center"
       android:orientation="vertical" >
   
   <Button
       android:id="@+id/help_button"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="@string/help_button" />
   
   </LinearLayout>

   Notice that the button text is a reference to a string resource: "@string/help_button". You'll add the string resource in the next step.

3. Open the strings.xml file in the res/values/ folder and add the following <string> child tag to the <resources> tag:

   <resources>
       <string name="help_button">Help</string>
   </resources>

4. Save the files, then run a build to make sure you don't get any error messages.

   The app should display a vertically centered Help button:

   

Adding an event listener for the Help button

You'd like your app to open the help center when the user clicks the Help button. To do so, you'll need an event listener that detects the click event, then opens the help center.

1. Switch to the MainActivity.java file in the Android Studio editor.

2. In the onCreate(Bundle) handler, and after the SDK initialization statements, declare a local Button variable and assign your layout button to it (highlighted):

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       // SDK initialization and identity
       Button helpCenterButton = (Button) findViewById(R.id.help_button);
   }

   The R.id.help_button id is defined by the line android:id="@+id/help_button" in the activity_main.xml layout file. The "@+id/" expression creates the id.

   Note that you must cast the View to Button before assigning it to your Button-typed variable.

3. The Button string is probably red, so click anywhere in it and press Option+Enter (Mac) or Alt+Enter (Windows). Android Studio should add the following import statement to your file:

   import android.widget.Button;

4. Add the following click event listener after the variable assignment (highlighted):

   Button helpCenterButton = (Button) findViewById(R.id.help_button);
   helpCenterButton.setOnClickListener(new View.OnClickListener() {
       @Override
       public void onClick(View v){
           // show the help center
       }
   });

   The string View in View.OnClickListener() should turn red, indicating an undefined symbol. Click anywhere in the red text, press Option+Enter (Mac) or Alt+Enter (Windows), and select Import Class if prompted. Android Studio should add the following import statement to your file:

   import android.view.View;

5. Replace the "show the help center" comment in the onClick(View) method with the following statement:

   HelpCenterActivity.builder()
       .show(MainActivity.this);

   Make sure MainActivity in the show() method is the name of the activity class you're in (in my case, public class MainActivity...).

   The HelpCenterActivity text should turn red. Click anywhere in it, press Option+Enter (Mac) or Alt+Enter (Windows), and select Import Class if prompted. Android Studio should add the following import statement to your file:

   import zendesk.support.guide.HelpCenterActivity;

That's it. The completed MainActivity subclass should look as follows:

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Zendesk.INSTANCE.init(this, "https://omniwear.zendesk.com",
                "23705744c16d8e0698b45920f18aa26e43d7",
                "mobile_sdk_client_b7fd695c0e9a6056");

        Identity identity = new AnonymousIdentity();
        Zendesk.INSTANCE.setIdentity(identity);

        Support.INSTANCE.init(Zendesk.INSTANCE);

        Button helpCenterButton = (Button) findViewById(R.id.help_button);
        helpCenterButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v){
                HelpCenterActivity.builder()
                    .show(MainActivity.this);
            }
        });
    }
}

You should have the following import statements at the top of the file:

package com.sample.mysampleapp;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.Button;

import zendesk.core.AnonymousIdentity;
import zendesk.core.Identity;
import zendesk.core.Zendesk;
import zendesk.support.Support;
import zendesk.support.guide.HelpCenterActivity;

Testing the integration

Build and test the application in the emulator. After tapping the Help button, your help center should open in the app and let you browse and search the content.

Note: If you do not see the help center, delete your app from the emulator and run a build again.

The help center also lets users submit support requests (tickets) and view their open requests. Tap the speech bubble on the lower-right to try it out.

Next steps

At this point you should have a working Android application that lets users open your help center and browse content. Use this sample application to experiment with the rest of the framework.

For example, you can limit the number of articles displayed by specifying a list of section or category ids. You can also scope the content by supplying a list of labels. See the developer docs to learn how.

Put your project under git and create branches to try out different things. You can always reset if something goes horribly wrong.