Working with the ASAP SDK for Android

Working with the ASAP SDK for Android

SDK v2.0

Introduction

The ASAP SDK for Android makes help available within quick reach for the end-users of your Android app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your:
  • Customer support team (to raise tickets or chat with support agents)
  • Knowledge base (to access help articles)
  • User community (to interact with other users of the app)
What this addition means for end-users is that they do not have to exit your app and visit your website or send an email to contact you for support. They can easily seek help right from within your app, thereby saving time and enjoying a superior customer experience.
If you are a current user of the ASAP SDK (versions up to 1.2.7), you need to migrate the existing code to use v2.0. For instructions on how to do this, please refer to the Migrating from v1.x to v2.0 section of this article.

Setting Up the SDK in Zoho Desk

The first step to including the ASAP add-on within your Android app is to create and register the add-on in Zoho Desk. To create the add-on, perform the following steps.
Go to this path in Zoho Desk: SetupChannelsASAP.
  1. In the Setup pane on the left, under ASAP, click the + button next to Mobile. The Create Mobile Add-On page appears.

  2. Under Add-On Details, configure the following settings:
    1. Name: Name for the ASAP add-on. This name is only for reference; it does not appear anywhere on the app UI.
    2. Available for: Departments for which this ASAP add-on must be enabled
    3. Bundle ID: In the Android field, enter the bundle ID of your Android app. (Bundle ID is nothing but the applicationId of your Android app. You can retrieve this information from the app level build.gradle file.)
      Note: Bundle ID is mandatory for enabling Live Chat and sending push notifications.
    4. Live Chat: Toggle switch for enabling/disabling Live Chat.
      Note: The Live Chat component reflects the settings configured for the chat channel in your help desk portal. Therefore, any change required must be done via the Setup page in Zoho Desk.
    5. Push Notifications : Toggle switch for enabling/disabling push notifications. To enable push notifications, enter the GCM/FCM server key in the Enter GCM/FCM key field. (You can retrieve this key by accessing the following path in Firebase Console: Project SettingsCloud MessagingServer Key ).
      Note: JWT-based user authentication is mandatory for enabling notifications. Push notifications related to tickets are not sent to anonymous users.
    6. Authentication Method: User authentication setting for the add-on
      1. Anonymous - In this method, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
      2. JWT - In this method, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view and track the status of the tickets they submitted, reply/comment to a ticket, and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
  3. Click Save.
A new section called Code Snippet appears. This section displays the Org ID, App ID, and Deployment type details of your app. These details are vital for initializing the ASAP SDK in your app.

Integrating the SDK with Your App

The next step is to integrate the ASAP SDK with your Android app using Maven.

To integrate the SDK with your app, include the following code in the root level build.gradle file.
repositories {
   jcenter()
   google()
   maven { url 'http://maven.zohodl.com/' }
}
Note: The ASAP SDK was developed using Android Architecture Components. Therefore, it is essential to include maven.google.com/google() in the app code.
Next, include the dependency required for the SDK.

Include the dependency code required in the dependencies section of the app level build.gradle file.
  1. 'com.zoho.desk:asapsdk:2.0.2' - ASAP SDK with default UI; includes Live Chat.
  2. 'com.zoho.desk:asap:2.0.2' - ASAP SDK with default UI; does not include Live Chat.
  3. 'com.zoho.desk:asap-api:2.0.2' - ASAP SDK without UI. Serves as the API provider.

dependencies {
   implementation 'com.zoho.desk:asapsdk:2.0.2'
}
The SDK is now integrated with your app. The configuration details of the ASAP SDK are as follows:
  • compileSdkVersion - 30
  • supportLibVersion - 27.1.1
  • minSdkVersion - 16
  • targetSdkVersion - 30
ProGuard Setup
If ProGuard and Minify are enabled, you must include the following rules in the proguard-rules.pro file.
-dontwarn com.squareup.okhttp.**
-keep class android.support.v7.widget.SearchView { *; }
-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn retrofit2.**
-dontwarn com.zoho.desk.**


Initializing the SDK in Your App

Next, you must initialize the SDK in your app.
The following three keys are crucial in this step:
  • Org ID
  • App ID
  • Datacenter
The value s of thes e keys appear under the Code Snippet section in the setup page of the ASAP add-on, in Zoho Desk.
To initialize the SDK in your app, add the following code snippet to a subclass of the Application class.
import android.app.Application;
import com.zoho.desk.asap.api.ZohoDeskPortalSDK;

public class MyApplication extends Application {
   public static ZohoDeskPortalSDK apiProvider;
   @Override 
   public void onCreate() {
      super.onCreate();
      ZohoDeskPortalSDK.Logger.enableLogs();
      apiProvider = ZohoDeskPortalSDK.getInstance(getApplicationContext());
      apiProvider.initDesk(orgId, appId, datacenterValue);
   }
}
Note
Datacenter values according to the deployment type are as follows:
CN - DataCenter.CN
EU - DataCenter.EU
US - DataCenter.US
IN - DataCenter.IN
AU - DataCenter.AU

Displaying Help Components

SDK Dashboard
The SDK dashboard is the screen through which end-users access your help center. This dashboard displays icons/buttons that provide access to your knowledge base, user community, customer support team (through the ticket submission form), tickets list (list of tickets submitted by users who are logged in), and live chat (to interact with a customer support agent in real time).
Note: The Live Chat module is not enabled by default in the SDK UI. You must first enable it in your Zoho Desk portal.
The following method displays the SDK dashboard.
ZDPortalHome.show(MainActivity.this);

SDK Dashboard with overridden configuration
The following method displays the SDK dashboard with its configuration overridden.
ZDPHomeConfiguration homeConfiguration = new ZDPHomeConfiguration.Builder()
.showKB(true)
.showMyTickets(true)
.showCommunity(true)
.showLiveChat(true)
.showNavDrawer(true).build();
ZDPortalHome.show(MainActivity.this, homeConfiguration);
Live Chat
Live Chat is the module through which end-users can interact with a customer support agent in real time.
The following method displays the Live Chat module.
ZDPortalChat.show(activity);
activity is the activity instance that triggers the Live Chat module.

Displaying Details of Anonymous Users to Agents
When an anonymous user contacts customer support via chat, their details usually do not appear on the agent's screen. However, you can configure the A SAP add-on to display these details after receiving them from the user.
To configure this setting, use the following method.
ZDPortalChatUser chatUser = new ZDPortalChatUser();
chatUser.setName(name);
chatUser.setEmail(email);
chatUser.setPhone(phone);
ZDPortalChat.setGuestUserDetails(chatUser);

Help Center (Knowledge Base)
Help Center is the module through which end-users can access help articles in your knowledge base.
The following method displays the help center (knowledge base).
ZDPortalKB.show(activity);
activity is the activity instance that triggers the Knowledge Base module.

Submit Ticket
Submit Ticket is the screen through which end-users can submit their questions/requests as support tickets.
The following method displays the Submit Ticket Screen.
ZDPortalSubmitTicket.show(activity);
activity is the activity instance that triggers the Submit Ticket screen.

If you want your app to subscribe to the Submit Ticket event, use the following method, which includes an event callback.
ZDPortalSubmitTicket.show(activity, new ZDPortalCallback.CreateTicketCallback() {
   @Override
   public void onTicketCreated(Ticket ticket) {
      //Ticket created
   }
   @Override
   public void onException(ZDPortalException e) {
      //Exception   
   }
} : null);
activity is the activity instance that triggers the Submit Ticket screen.

CreateTicketCallback is the callback object that sends ticket information when a ticket is submitted via the Submit Ticket screen.
Note: If an authenticated user submits a ticket, all ticket details are sent to your app. If a guest user submits a ticket, only the ticket number is sent.

My Tickets
My Tickets is the screen through which end-users can access, track, and edit the tickets they submitted.

The following method displays the My Tickets screen.
ZDPortalTickets.show(activity);
activity is the activity instance that triggers the My Tickets screen.

User Community
User Community is the module through which end-users can access discussion forums and interact with other users for sharing knowledge.
The following method displays the user community.
ZDPortalCommunity.show(activity);
activity is the activity instance that triggers the Community module.

Authenticating Users in the SDK

To access the tickets they submitted, end-users of your app must have an identity so that they can authenticate themselves as a user of the Zoho Desk portal. This authentication is made possible in Zoho Desk via the JSON Web Token (JWT).

Zoho Desk supports two types of authentication: Anonymous and JWT.
  • Anonymous - In this type, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
  • JWT - In this type, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view the tickets they submitted and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
For detailed information on how to configure JWT-based user authentication in the ASAP SDK, refer to this article.

The following code snippet authenticates users in the SDK.
if(!MyApplication.deskInstance.isUserSignedIn()) { 
   MyApplication.deskInstance.setUserToken(userToken, new ZDPortalCallback.SetUserCallback() { 
      @Override
      public voidonUserSetSuccess() { 
         //User set success 
      } 
      @Override
      public voidonException(ZDPortalException e) { 
         //Exception 
      } 
   });
}
In the code snippet above:
  • userToken is the encrypted unique information that identifies the user (email address, for example).
  • setUserToken is the function that inputs the user token of the user.
  • callback is the ZDPortalCallback.SetUserCallback instance that will be called after userFetch is executed.
The setUserToken function must be executed only if a user has not signed into the SDK. Therefore, you must configure the ASAP add-on to first check if a user has signed in or not. To perform this check, use the following code.
boolean isUserLoggedIn = MyApplication.deskInstance.isUserSignedIn();

Logging Users out from the SDK

To log a user out from the SDK, use the following method.
MyApplication.deskPortalSDK.logout(new ZDPortalCallback.LogoutCallback() { 
   @Override 
   public void onLogoutSuccess() { 
      //User logged out 
   } 
   @Override 
   public void onException(ZDPortalException e) { 
   } 
});
After this method is called, the authenticated user is treated as an anonymous user.

Clearing Local Data

All the data stored locally in the device is automatically cleared when an authenticated user signs out from the ASAP add-on.
However, if local data needs to be cleared for anonymous users too, use the following method.
MyApplication.deskInstance.clearDeskPortalData();

Customizing the Add-On UI

The ASAP SDK provides you with the option to customize the UI of the add-on as required.

Predefined Themes
The SDK UI comes with two predefined themes: light and dark. The following methods help you apply these themes.

Method for Applying the Light Theme (Default)
ZDPortalConfiguration.setThemeResource(R.style.deskTheme_Light);
Method for Applying the Dark Theme
ZDPortalConfiguration.setThemeResource(R.style.deskTheme_Dark);
Customized Themes
You can customize the overall theme of the SDK using the following line of code.
ZDPortalConfiguration.setThemeResource(R.style.deskTheme);
ThemeResource must extend either deskTheme_Light or deskTheme_Dark.

The following image shows the attributes to customize in your theme.

Using Custom Fonts
The default font on the add-on UI is Roboto, but you can use other fonts of your choice too.

The following code snippet lets you customize the font on the UI.
<style name="deskTheme" parent="deskTheme_Light">
   <!-- Customize your theme here. -->
   <item name="colorPrimary">@color/colorPrimary </item>
   <item name="colorPrimaryDark">@color/colorPrimaryDark </item>
   <item name="colorAccent">@color/colorAccent </item>
   <item name="android:fontFamily">@font/dosis_regular </item>
</style>
Note: If you do not use a custom font, the add-on displays the system font by default.

Changing Language Settings

The ASAP SDK supports 47 languages. You can set any language of your choice, based on the geographical location of the end-users of your app.
Below is the code that helps you set the language for the ASAP add-on.
ZDPortalConfiguration.setLanguage("en");
The table below lists all languages supported.

Language
Locale Code
English (UK)
en-GB
English (US)
en-US
German
de
Spanish
es
Catalan
ca
French
fr
French (Canada)
fr-ca
Italian
it
Russian
ru
Chinese
zh
Chinese (Taiwan)
zh-tw
Turkish
tr
Dutch
nl
Danish
da
Portuguese
pt
Japanese
ja
Swedish
sv
Polish
pl
Arabic
ar
Hebrew
he
Afrikaans
af
Czech
cs
Bulgarian
bg
Finnish
fi
Greek
el
Hungarian
hu
Indonesian
id
Norwegian (Bokmal)   
nb
Romanian
ro
Thai
th
Ukrainian
uk
Vietnamese
vi
Urdu
ur
Hindi
hi
Telugu
te
Kannada
kn
Tamil
ta
Marathi
mr
Korean
ko
Persian
fa
Bengali
bn
Gujarati
gu
Malay
ms
Malayalam
ml
Slovak
sk
Croatian
hr
Slovenian
sl

If your app supports only a handful of languages and not all 47 mentioned in the table, you can configure the ASAP add-on such that only the languages you want are supported in it. 

To do this, include the following code snippet in the build.gradle file. 
android {
    defaultConfig {
        ...
        resConfigs "en", "ta", "fi"
    }
}
For instance, the snippet mentioned above includes only English, Tamil, and Finnish in the add-on, and excludes the other languages.

For more information on the resConfigs key, click here

Customizing UI Strings

The ASAP SDK facilitates customization of the text that appears on the different screens of the add-on. The text includes UI labels for help modules, error messages, and general information. To change the text, perform the following steps:
  1. In the strings.xml file of your app, include the keys that are relevant to the SDK UI. (For the list of keys supported, refer to the table below.)
  2. Compile the code and verify.
The table below lists the different keys in the default ASAPLocalizable.strings file.
Key
Default Text
Description
DeskPortal.Dashboard.Heading
"Customer Support"
Text that appears on the help center dashboard
DeskPortal.Dashboard.helpcenter.title
"Knowledge Base"
Title of the knowledge base module icon on the dashboard
DeskPortal.Dashboard.helpcenter.description
"Browse our extensive repository of help articles"
Text that describes the knowledge base
DeskPortal.Dashboard.community.title
"Community"
Title of the user community module icon on the dashboard
DeskPortal.Dashboard.community.description
"Find and share solutions with the user community"
Text that describes the user community
DeskPortal.Dashboard.addticket.title
"Submit Ticket"
Title of the ticket submission module icon on the dashboard
DeskPortal.Dashboard.addticket.description
"Seek help from our agents"
Text that describes the ticket submission screen
DeskPortal.Dashboard.myticket.title
"My Tickets"
Title of the my tickets icon on the dashboard
DeskPortal.Dashboard.myticket.description
"View and manage tickets that you submitted"
Text that describes the my tickets screens
DeskPortal.Helpcenter.article.detail.relatedtitle
"Related Articles"
Text that appears below any help article in the knowledge base
DeskPortal.Helpcenter.article.detail.vote.description
"Was this article helpful?"
Text that seeks feedback from the user
DeskPortal.Helpcenter.feedback.title
"Feedback"
Title of the feedback form
DeskPortal.Helpcenter.feedback.description
"We're sorry the article wasn't helpful."
Text that appears when a user downvotes an article
DeskPortal.Myticket.option.closeticket
"Close Ticket"
Text for option that lets the user close a ticket they submitted
DeskPortal.Error.message.reload
"Retry"
Error message that appears if ticket submission fails
DeskPortal.Network.failed.error.message
"No Internet connection"
Error message that indicates loss of connectivity
DeskPortal.Dashboard.livechat.title
"Live Chat"
Title of the live chat module on the help center dashboard
DeskPortal.Addticket.title
"Add Ticket"
Title of the ticket submission form

Enabling Notifications

You can configure the ASAP add-on to send notifications to end-users when an agent responds via chat.
Note: Make sure that Push Notifications settings are configured in the ASAP add-on setup page on Zoho Desk.
To enable push notifications for Live Chat and Tickets, include the following code snippet after initializing the SDK.
MyApplication.deskInstance.enablePush("fcmId");
fcmId is the client token used for registering the device. You can retrieve this token using the FirebaseInstanceId.getInstance().getToken(); method.

To disable push notifications, include the following code snippet.
MyApplication.deskInstance.disablePush("fcmId");
To configure UI and navigation for notifications, add the following code snippet to the onReceived() method of your NotificationReceiver class.
ZDPortalConfiguration.handleNotification(Context context, Map data, int icon);
context is the appContext. Map refers to the notification data that is received. icon is the application icon that must appear in the notification.

Programmatically Adding Tickets

While end-users can manually submit tickets through the ASAP add-on, you can also configure your app to automatically record tickets when certain events occur in the app. For instance, if you run a clothing business and your app fails to load the For Women screen when a user tries to access it, this failure instance can be automatically recorded as a ticket in your help desk. The user would not need to visit your help center and manually submit a ticket.

To make this automatic submission of tickets possible, incorporate the following method in your app code.
ZDPortalTicketsAPI.createTicket(new CreateTicketCallback() {
   @Override
   public void onTicketCreated(Ticket ticket) {
   }
   @Override
   public void onException(ZDPortalException exception) {
   }
}, ticketData, params);
ticketData - instance of HashMap<String, Object> key-value EmailAddress, Subject, and DepartmentID are mandatory parameters in ticketData.

To fetch the IDs of the departments in your help desk portal, use the following method.
ZDPortalAPI.getDepartments(new ZDPortalCallback.DepartmensCallback() { 
   @Override 
   public void onDepartmentsDownloaded(DepartmentsList response) { 
   } 
   @Override 
   public void onException(ZDPortalException exception) { 
   } 
});
To fetch information on the products configured in a department, use the following method.
HashMap<String, String> options = new HashMap<>(); 
options.put("from", String.valueOf(1)); 
options.put("limit", String.valueOf(100)); 
options.put("departmentId", departmentId); 
ZDPortalAPI.getProductsList(new ZDPortalCallback.ProductsCallback() { 
   @Override 
   public void onProductsDownloaded(ProductsList productsList) { 
      productsMap.put(departmentId, productsList.getData()); 
      responseLiveData.setValue(productsList.getData()); 
   } 
   @Override 
   public void onException(ZDPortalException exception) { 
   } 
}, options);
To fetch the fields configured in the ticket layout of a department, use the following method.
ZDPortalTicketsAPI.getTicketFields(new TicketFieldsCallback() {
   @Override
   public void onTicketFieldsDownloaded(TicketFieldsList ticketFieldsList) {
   }
   @Override
   public void onException(ZDPortalException exception) {
   }
}, fieldsParams, "apiName");
To include a file attachment in the ticket, use the following method.
ZDPortalTicketsAPI.uploadAttachment(new UploadAttachmentCallback() {
   @Override
   public void onAttachmentUploaded(ASAPAttachmentUploadResponse response) {
   }
   @Override
   public void onException(ZDPortalException exception) {
   }
}, fileTobeUploaded, null);

Knowledge Base

These methods help you display the Knowledge Base module and all associated content on the ASAP add-on.
Category Deep-linking
The following method displays the list of categories/sub-categories in your knowledge base and the help articles under each category.
ZDPortalKB.showCategoryWithPermalink(activity, permaLink);
  1. activity is the instance of the activity.
  2. permalink is the URL of the knowledge base category.


For instance, in the URL in the image above, the portion following "/kb/" is the permalink of the category. You can pass this portion as the path of the category or sub-category.

Article Deep-linking
The following method displays the content of a help article right within your ASAP add-on.
ZDPortalKB.showArticleWithPermalink(activity, permaLink);
  1. activity is the instance of the activity.
  2. permalink is the URL of the help article.


For instance, in the URL in the image above, the portion following "/articles/" is the permalink of the article.

Community

These methods help you display the Community module and all associated content on the ASAP add-on.

Custom-Configuring Community Actions
Users can perform a range of actions, including editing and deleting topics; and adding, editing, and deleting comments, in the community module.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the community through the ASAP add-on.
ZDPCommunityConfiguration communityConfiguration = new ZDPCommunityConfiguration(); 
communityConfiguration.setTopicEditAllowed(false); 
communityConfiguration.setTopicDeleteAllowed(false); 
communityConfiguration.setReplyAllowed(true); 
communityConfiguration.setReplyEditAllowed(true); 
communityConfiguration.setReplyDeleteAllowed(false); 
ZDPortalCommunity.setConfiguration(communityConfiguration);
Getting the Most Popular Topics
The following API fetches the forum topics with the most number of likes.
HashMap<String, String> params = new HashMap<>();
params.put("from", "1");
params.put("limit", "5");
ZDPortalCommunityAPI.getMostPopularTopics(new ZDPortalCallback.CommunityTopicsCallback() {
      @Override
      public void onCommunityTopicsDownloaded(DeskTopicsList deskTopicsList) {
      }
      @Override
      public void onException(ZDPortalException e) {
      }
}, params);
Allowed Params
  1. categoryId - string - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value null.
  2. filterType - string - Type of forum topic. Values allowed are: QUESTION, IDEA, ANNOUNCEMENT, PROBLEM , and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not
Getting the Most Discussed Topics
The following API fetches the forum topics with the most number of comments.
HashMap<String, String> params = new HashMap<>();
params.put("from", "1");
params.put("limit", "5");
ZDPortalCommunityAPI.getMostDiscussedTopics(new ZDPortalCallback.CommunityTopicsCallback() {
   @Override
   public void onCommunityTopicsDownloaded(DeskTopicsList deskTopicsList) {
   }
   @Override
   public void onException(ZDPortalException e) {
   }
}, params);
Allowed Params
  1. categoryId - string - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value null.
  2. filterType - string - Type of forum topic. Values allowed are: QUESTION, IDEA, ANNOUNCEMENT, PROBLEM, and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not

Tickets

These methods help you configure the Submit Ticket form the way you want, on the ASAP add-on.

Hiding Fields in the Submit Ticket Form
The Submit Ticket form in your ASAP add-on displays the same fields configured in the ticket layout in your Zoho Desk portal. If you want to hide any of the fields in the form, you can do so using the setTicketsFieldsListTobeShown() method.

You must pass the list of fields (apiNames) as strings in this method. You might also have to pass the departmentId key, depending on the department mapping of the add-on. For instance, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-ticket fields mapping in the Submit Ticket form.

After you include this method, the form displays only the fields you passed in the method. However, keep in mind that mandatory fields will not be hidden even if you do not pass their names in the method.
ZDPortalSubmitTicket.setTicketsFieldsListTobeShown(ticketListTobeShown, deptId);
  1. ticketListTobeShown - List of strings (apiName of the Ticket Fields)
  2. deptId - ID of the department for which you want to configure the Ticket Fields list.

Hiding Mandatory Fields in the Submit Ticket Form
If you absolutely want to hide a mandatory field in the form, you can do so, provided the value of the field is pre-filled. To do this, you must use the preFillTicketFields() method.

The preFillTicketFields() method proves useful when you want to pre-populate fields with values, such as auto-generated IDs or OS version of devices. To use this method, you must pass the list of PreFillTicketField objects. You should also pass the departmentId key, depending on the department mapping of the add-on. Just like in the case of the setTicketsFieldsListTobeShown() method, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-fields mapping.
ZDPortalSubmitTicket.preFillTicketFields(preFillTicketFields, deptId);
  1. preFillTicketFields - List of PreFillTicketField objects
  2. deptId - ID of the department for which you want to configure the Ticket Fields list.
The PreFillTicketField object contains three main properties:
  1. fieldApiName - string - apiName of the ticket field. You can retrieve the apiName of each field using the getTicketFields() method.
  2. fieldValue - object
    1. For multiselect fields, pass the values allowed, as a list of strings.
    2. For pick list fields, pass one of the values allowed, as a string.
    3. For date fields, pass the value as a string in the dd-MM-yyyy format.
    4. For dateTime fields, pass the value as a string in the dd-MM-yyyy HH:mm a format.
    5. For Boolean fields, pass a Boolean value.
    6. For all other field types, pass the values as string objects.
    7. Make sure that the values you pass adhere to the maxlength and decimal restrictions defined for the field.
  3. isEditable - Boolean - Key that defines if the value in the field is editable or not
Note: For more clarity, refer to the sample code here .
Custom-Configuring Ticket Actions
Users can perform a range of actions, including replying to, commenting on, and closing tickets.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the ticket submission screen on the ASAP add-on.
ZDPTicketConfiguration ticketConfiguration = new ZDPTicketConfiguration(); 
ticketConfiguration.setReplyAllowed(false); 
ticketConfiguration.setCommentAllowed(true); 
ticketConfiguration.setTicketUpdateAllowed(true); 
ticketConfiguration.setCommentEditAllowed(false); 
ticketConfiguration.setCommentDeleteAllowed(false); 
ZDPortalTickets.setConfiguration(ticketConfiguration);

Others

These methods help you perform a variety of other actions in your ASAP add-on.

Updating User Details
The following API helps update the details of users added to your help desk portal.
HashMap<String, String> params = new HashMap<>();
params.put("timeZone", "asia/kolkatta");
ZDPortalAPI.updateProfileDetails(new ZDPortalCallback.UserDetailsCallback() {
   @Override
   public void onUserDetailsSuccess(DeskUserProfile userProfile) {
   }
   @Override
   public void onException(ZDPortalException exception) {
   }
}, params);
Params
HashMap <String, String> data - Key and value pair. Keys included are: twitter, phone, facebook, name, displayName, mobile, countryLocale, and timeZone.

SDK Logging

The ASAP SDK also provides you with the option to fix errors that occur while using the add-on. This is made possible by SDK logging.
To enable logging for the SDK, include the following code snippet.
ZohoDeskPortalSDK.Logger.enableLogs();
After enabling SDK logging, you can check the console log for the errors and take necessary action.
Note: Some debug information related to the SDK is stored in logcat. Therefore, make sure that enableLogs() does not exist in the release build.

Release Notes

v2.0.2
  1. Incorporated the search preferences that exist for the help center in the web app. 
  2. Enabled the Share to social media option for community forum topics.

v2.0.1
  1. Enabled deep-linking for forum topics in the Community module. 

v2.0
  • Provided support for having a multilingual Knowledge Base. 
  • Included Conditional Layouts and Ticket Templates in the Add Ticket module.
  • Added an API provider as a separate lightweight framework containing all APIs available. You can build a custom UI and incorporate the APIs into it.  

SDK v1.0

Introduction

The ASAP SDK for Android makes help available within quick reach for the end-users of your Android app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your:
  • Customer support team (to raise tickets or chat with support agents)
  • Knowledge base (to access help articles)
  • User community (to interact with other users of the app)
What this addition means for end-users is that they do not have to exit your app and visit your website or send an email to contact you for support. They can easily seek help right from within your app, thereby saving time and enjoying a superior customer experience.

Setting Up the SDK in Zoho Desk

The first step to including the ASAP add-on within your Android app is to create and register the add-on in Zoho Desk.
To create the add-on, perform the following steps.
  1. Go to this path in Zoho Desk: Setup → Channels → ASAP.
  2. In the Setup pane on the left, under ASAP, click the + button next to Mobile. The Create Mobile Add-On page appears. 

  3. Under Add-On Details, configure the following settings:
    • Name: Name for the ASAP add-on. This name is only for reference; it does not appear anywhere on the app UI.
    • Available for: Departments for which this ASAP add-on must be enabled
    • Bundle ID: In the Android field, enter the bundle ID of your Android app. (Bundle ID is nothing but the applicationId of your Android app. You can retrieve this information from the app level build.gradle file.)
      Note: Bundle ID is mandatory for enabling Live Chat and sending push notifications.
    • Live Chat:Toggle switch for enabling/disabling Live Chat.
      Note: The Live Chat component reflects the settings configured for the chat channel in your help desk portal. Therefore, any change required must be done via the Setup page in Zoho Desk.
    • Push Notifications :Toggle switch for enabling/disabling push notifications. To enable push notifications, enter the GCM/FCM server key in the Enter GCM/FCM key field. (You can retrieve this key by accessing the following path in Firebase Console: Project Settings → Cloud Messaging → Server Key).
      Note: JWT-based user authentication is mandatory for enabling notifications. Push notifications related to tickets are not sent to anonymous users.
    • Authentication Method: User authentication setting for the add-on
      • Anonymous - In this method, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
      • JWT - In this method, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view and track the status of the tickets they submitted, reply/comment to a ticket, and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts). 
  4. Click Save.
A new section called Code Snippet appears. This section displays the Org ID, App ID, and Deployment type details of your app. These details are vital for initializing the ASAP SDK in your app. 

Integrating the SDK with Your App

The next step is to integrate the ASAP SDK with your Android app using Maven.
To integrate the SDK with your app, include the following code in the root level build.gradle file.
repositories {
   jcenter()
   maven { url 'https://maven.google.com/' }
   maven { url 'http://maven.zohodl.com/' }
}
Note: The ASAP SDK was developed using Android Architecture Components. Therefore, it is essential to include maven.google.com in the app code.
Next, include the dependency required for the SDK.
Include the following code in the dependencies section of the app level build.gradle file.
dependencies {
   compile 'com.zoho.desk:asapsdk:1.2.8'
}
The SDK is now integrated with your app.
The configuration details of the ASAP SDK are as follows:
  • compileSdkVersion - 30
  • supportLibVersion - 26.1.0
  • minSdkVersion - 16
  • targetSdkVersion - 30
ProGuard Setup
If ProGuard and Minify are enabled, you must include the following rules in the proguard-rules set.
-keep class com.zoho.** {*;}
-keep interface android.support.v7.** { *; }
-keep class android.support.v7.** { *; }
-keep interface android.support.v4.** { *; }
-keep class android.support.v4.** { *; }
-keepattributes Signature
-keepattributes Annotation
-keep class okhttp3.* { *; }
-keep interface okhttp3.* { *; }
-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn com.zoho.accounts.**
-dontwarn com.squareup.okhttp.**
-dontwarn okio.**
-dontwarn retrofit2.**

Initializing the SDK in Your App

Next, you must initialize the SDK in your app.
The following three keys are crucial in this step:
  • Org ID
  • App ID
  • Datacenter
The values of these keys appear under the Code Snippet section in the setup page of the ASAP add-on, in Zoho Desk.
To initialize the SDK in your app, add the following code snippet to a subclass of the Application class.
import android.app.Application;
import com.zoho.deskportalsdk.DeskConfig;
import com.zoho.deskportalsdk.ZohoDeskPortalSDK;

public class MyApplication extends Application {
    public static ZohoDeskPortalSDK deskInstance;
    @Override
    public void onCreate() {
        super.onCreate();
        ZohoDeskPortalSDK.Logger.enableLogs();
        DeskConfig config = new DeskConfig.Builder().build();
        deskInstance = ZohoDeskPortalSDK.getInstance(this);
        deskInstance.initDesk(orgId, appId, dataCenterValue, config);
    }
}
Datacenter values according to the deployment type are as follows :
CN - DataCenter.CN
EU - DataCenter.EU
US - DataCenter.US
IN - DataCenter.IN

Displaying Help Components

Given below are the methods for displaying individual help components on the add-On UI. These methods display the components according to their default configuration and the settings configured in your Zoho Desk portal. The components in the default configuration vary according to the Zoho Desk edition in use.
SDK Dashboard
The SDK dashboard is the screen through which end-users access your help center. This dashboard displays icons/buttons that provide access to your knowledge base, user community, customer support team (through the ticket submission form), tickets list (list of tickets submitted by users who are logged in), and live chat (to interact with a customer support agent in real time).
Note: Live chat is not enabled by default in the SDK UI. You must first enable live chat in your Zoho Desk portal.
The following method displays the SDK dashboard.
MyApplication.deskInstance.startDeskHomeScreen(activity.this);
activity is the activity instance that triggers the SDK dashboard.

SDK Dashboard with overridded configuration
The following method displays the SDK dashboard with its configuration overridden.
DeskConfig deskConfig = new DeskConfig.Builder().showCommunity(false).build();
MyApplication.deskInstance.startDeskHomeScreen(activity.this, deskConfig);
activity is the activity instance that triggers the SDK dashboard.
In this example code snippet, the dashboard is configured such that the Community component is hidden.
You also have the option to not display the SDK dashboard on your app and still provide access to individual help components. The following methods help you display the individual components with their default configuration.
Live Chat
Live chat is the component through which end-users can interact with a customer support agent in real time.
The following method displays the live chat component.
MyApplication.deskInstance.startLiveChat();
Help Center (Knowledge Base)
Help center is the component through which end-users can access help articles in your knowledge base
The following method displays the help center (knowledge base).
MyApplication.deskInstance.startHelpCenter(activity.this);
activity is the activity instance that triggers the knowledge base.
Submit Ticket
Submit Ticket is the screen through which end-users can submit their questions/requests as support tickets.
The following method displays the Submit Ticket Screen.
MyApplication.deskInstance.startNewTicket(activity.this);
activity is the activity instance that triggers the Submit Ticket screen.
If you want your app to subscribe to the submit ticket event, use the following method, which includes an event callback.
MyApplication.deskInstance.startNewTicket(activity.this, new DeskCallback.DeskAddTicketCallback() {
     @Override
     public void onTicketAdded(DeskTicketResponse deskTicketResponse) {
         Toast.makeText(MainActivity.this, "onTicketAdded", Toast.LENGTH_SHORT).show();
     }

     @Override
     public void onException(DeskException e) {
         Toast.makeText(MainActivity.this, "onException", Toast.LENGTH_SHORT).show();
     }
 });
activity is the activity instance that triggers the Submit Ticket screen.
DeskAddTicketCallback is the callback object that sends ticket information when a ticket is submitted via the Submit Ticket screen.
Note: If an authenticated user submits a ticket, all ticket details are sent to your app. If a guest user submits a ticket, only the ticket number is sent.
My Tickets
My Tickets is the screen through which end-users can access, track, and edit the tickets they submitted.
The following method displays the My Tickets screen.
MyApplication.deskInstance.startTickets(activity.this);
activity is the activity instance that triggers the My Tickets screen.
User Community
User community is the component through which end-users can access discussion forums and interact with other users for sharing knowledge.
The following method displays the user community.
MyApplication.deskInstance.startCommunity(activity.this);
activity The following method displays the user community.

Authenticating Users in the SDK

To access the tickets they submitted, end-users of your app must have an identity so that they can authenticate themselves as a user of the Zoho Desk portal. This authentication is made possible in Zoho Desk via the JSON Web Token (JWT).
Zoho Desk supports two types of authentication: Anonymous and JWT.
  • Anonymous - In this type, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
  • JWT - In this type, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view the tickets they submitted and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
For detailed information on how to configure JWT-based user authentication in the ASAP SDK, refer to this document
The following code snippet authenticates users in the SDK.
if(!isUserLoggedIn) {
    MyApplication.deskInstance.setUserToken("userToken", new DeskCallback.DeskSetUserCallback() {
        @Override
        public void onUserSetSuccess() {
        }
        @Override
        public void onException(DeskException exception) {
        }
    });
} else{
    //User already signed into SDK
}
In the code snippet above:
  • userToken is the encrypted unique information that identifies the user (email address, for example).
  • setUserToken is the function that inputs the user token of the user. 
  • callback is the DeskCallback.DeskSetUserCallback instance that will be called after userFetch is executed.
The setUserToken function must be executed only if a user has not signed into the SDK. Therefore, you must configure the ASAP add-on to first check if a user has signed in or not. To perform this check, use the following code. 
boolean isUserLoggedIn = MyApplication.deskInstance.isUserSignedIn();
If the value returned is true, it means the user is already signed in to the SDK. So, the setUserToken function need not be executed. 
Logging Users out from the SDK
To log a user out from the SDK, use the following method.
MyApplication.deskInstance.removeUser(new DeskCallback.DeskRemoveUserCallback() {
    @Override
    public void onUserRemoveSuccess() {
        //user removed from SDK.
    }

    @Override
    public void onException(DeskException exception) {
    }
});
After this method is called, the authenticated user is treated as an anonymous user.

Clearing Local Data

All the data stored locally in the device is automatically cleared when an authenticated user signs out from the ASAP add-on.
However, if local data needs to be cleared for anonymous users too, use the following method.
MyApplication.deskInstance.clearDeskPortalData();

Hiding Help Components

By default, the ASAP SDK displays all help components available, depending on the Zoho Desk edition in use and settings configured in the Zoho Desk portal. However, you can also show or hide individual help components on your app, as required.
The following methods help disable individual help components on the add-on.
To Hide the Help Center (Knowledge Base)
DeskConfig config = new DeskConfig.Builder().showHelpCenter(false).build();
To Hide the Submit Ticket Screen
DeskConfig config = new DeskConfig.Builder().showCreateTicket(false).build();
To Hide the My Tickets Screen
DeskConfig config = new DeskConfig.Builder().showMyTickets(false).build();
To Hide the User Community
DeskConfig config = new DeskConfig.Builder().showCommunity(false).build();
To Hide the Navigation Drawer
DeskConfig config = new DeskConfig.Builder().showNavDrawer(false).build();
Note: You must send the configuration object in the deskInstance.initDesk function. For more details, refer to the Initializing the SDK in Your App section of this document. 

Customizing the Add-On UI

The ASAP SDK provides you with the option to customize the UI of the add-on as required.
Predefined Themes
The SDK UI comes with two predefined themes: light and dark. The following methods help you apply these themes.

Method for Applying the Light Theme (Default)
deskInstance.setThemeResource(R.style.deskTheme_Light);
Method for Applying the Dark Theme
deskInstance.setThemeResource(R.style.deskTheme_Dark);
Customized Themes
You can customize the overall theme of the SDK using the following line of code.
MyApplication.deskInstance.setThemeResource(R.style.deskTheme);
Theme resource must extend either deskTheme_Light or deskTheme_Dark.
The following image shows the attributes to customize in your theme.

Using Custom Fonts
The default font on the add-on UI is Roboto, but you can use other fonts of your choice too.
The following code snippet lets you customize the font on the UI.
<style name="deskTheme" parent="deskTheme_Light">
   <!-- Customize your theme here. -->
   <item name="colorPrimary">@color/colorPrimary </item>
   <item name="colorPrimaryDark">@color/colorPrimaryDark </item>
   <item name="colorAccent">@color/colorAccent </item>
   <item name="android:fontFamily">@font/dosis_regular </item>
</style>

Note: If you do not use a custom font, the add-on displays the system font by default.

Changing Language Settings

The ASAP SDK supports 12 languages. You can set any language of your choice, based on the geographical location of the end-users of your app.
Below is the code that helps you set the language for the ASAP add-on.
DeskConfig config = new DeskConfig.Builder().setLanguage("de").build();
The table below lists all languages supported.
Language
Locale Code
English
en
German
de
Spanish
es
French
fr
Italian
it
Russian
ru
Chinese
zh
Turkish
tr
Dutch
nl
Danish
da
Portuguese
pt
Japanese
ja

Customizing UI Text

The ASAP SDK facilitates customization of the text that appears on the different screens of the add-on. The text includes UI labels for help components, error messages, and general information. To change the text, perform the following steps:
  1. In the strings.xml file of your app, include the keys that are relevant to the SDK UI. (For the list of keys supported, refer to the table below.)
  2. Compile the code and verify.
Key
Default Text
Description
DeskPortal.Dashboard.Heading
"Customer Support"
Text that appears on the help center dashboard
DeskPortal.Dashboard.helpcenter.title
"Knowledge Base"
Title of the knowledge base module icon on the dashboard
DeskPortal.Dashboard.helpcenter.description
"Browse our extensive repository of help articles"
Text that describes the knowledge base
DeskPortal.Dashboard.community.title
"Community"
Title of the user community module icon on the dashboard
DeskPortal.Dashboard.community.description
"Find and share solutions with the user community"
Text that describes the user community
DeskPortal.Dashboard.addticket.title
"Submit Ticket"
Title of the ticket submission module icon on the dashboard
DeskPortal.Dashboard.addticket.description
"Seek help from our agents"
Text that describes the ticket submission screen
DeskPortal.Dashboard.myticket.title
"My Tickets"
Title of the my tickets icon on the dashboard
DeskPortal.Dashboard.myticket.description
"View and manage tickets that you submitted"
Text that describes the my tickets screen
DeskPortal.Helpcenter.article.detail.relatedtitle
"Related Articles"
Text that appears below any help article in the knowledge base
DeskPortal.Helpcenter.article.detail.vote.description
"Was this article helpful?"
Text that seeks feedback from the user
DeskPortal.Helpcenter.feedback.title
"Feedback"
Title of the feedback form
DeskPortal.Helpcenter.feedback.description
"We're sorry the article wasn't helpful."
Text that appears when a user downvotes an article
DeskPortal.Myticket.option.closeticket
"Close"
Text for option that lets the user close a ticket they submitted
DeskPortal.Error.message.reload
"Retry"
Error message that appears if ticket submission fails
DeskPortal.Error.message.noInternet
"No Internet connection"
Error message that indicates loss of connectivity
DeskPortal.Dashboard.livechat.title
"Live Chat"
Title of the live chat module on the help center dashboard
DeskPortal.Addticket.title
"Add Ticket"
Title of the ticket submission form

Enabling Notifications

You can configure the ASAP add-on to send notifications to end-users when an agent responds via chat.
Note: Make sure that Push Notifications settings are configured in the ASAP add-on setup page on Zoho Desk.
To enable push notifications for live chat, include the following code snippet after initializing the SDK.
MyApplication.deskInstance.enablePush("fcmId");
fcmId is the client token used for registering the device. You can retrieve this token from the FirebaseInstanceId.getInstance().getToken(); method. 
To disable push notifications, include the following code snippet.
MyApplication.deskInstance.disablePush("fcmId");
You can also handle the UI and navigation for notifications. To do this, add the following code snippet to the onReceived() method of your NotificationReceiver class. 
MyApplication.deskInstance.handleNotification(Context context, Map data, int icon);
context is the appContext. Map refers to the notification data that is received. icon is the application icon that must appear in the notification.

Displaying Details of Anonymous Users to Agents

When an anonymous user contacts customer support via chat, their details usually do not appear on the agent's screen. However, you can configure the ASAP add-on to display these details after receiving them from the user.
To configure this setting, use the following method.
DeskUser user = new DeskUser();        
user.setEmail(email);        
user.setPhone(phone);        
user.setName(name);        
MyApplication.deskInstance.setGuestUserDetails(user);
Additionally, agents can convert chat conversations into tickets, if more interactions with the user are required later. The email ID is a mandatory parameter to make this conversion possible.

Programmatically Adding Tickets

While end-users can manually submit tickets through the ASAP add-on, you can also configure your app to automatically record tickets when certain events occur in the app.
For instance, if you run a clothing business and your app fails to load the For Women screen when a user tries to access it, this failure instance can be automatically recorded as a ticket in your help desk. The user would not need to visit your help center and manually submit a ticket. 
To make this automatic submission of tickets possible, incorporate the following method in your app code.
DeskNewTicketData ticketData = new DeskNewTicketData();
ticketData.setEmail("emailAddress@test.com");
ticketData.setContactName("ContactName");
ticketData.setDepartmentId(departmentId);
ticketData.setSubject("Subject of the Ticket");
ticketData.setDescription("Description of the ticket");

MyApplication.deskInstance.addGuestTicket(ticketData, new DeskCallback.DeskAddGuestTicketCallback() {
      @Override
      public void onTicketAdded() {
            Log.i("APITEST", "addGuestTicket success ");
      }
      @Override
      public void onException(DeskException exception) {
            Log.i("APITEST", "addGuestTicket exception "+exception.getErrorMsg());
      }
});
EmailAddressSubject, and DepartmentID are mandatory parameters in the method call. 
To fetch the IDs of the departments in your help desk portal, use the following method.
MyApplication.deskInstance.getDepartmentsList(new DeskCallback.DeskDepartmentsCallback() {
  @Override
  public void onDepartmentsLoaded(DeskDepartmentsList response) {
        Log.i("APITEST", "getDepartmentsList success ");
  }
  @Override
  public void onException(DeskException exception) {
        Log.i("APITEST", "getDepartments exception "+exception.getErrorMsg());
  }
});
To fetch information on the products configured in a department, use the following method.
public void getProducts(View view) {
  MyApplication.deskInstance.getProductsList(new DeskCallback.DeskProductsCallback() {
        @Override
        public void onProductsCompleted(DeskProductsList response) {
              Log.i("APITEST", "getProducts success");
        }
        @Override
        public void onException(DeskException exception) {
              Log.i("APITEST", "getProducts exception "+exception.getErrorMsg());
        }
  }, departmentId,1,10);
}
To fetch the fields configured in the ticket layout of a department, use the following method.
public void getTicketsFields(View view) {
  MyApplication.deskInstance.getTicketsFieldsList(new DeskCallback.DeskTicketsFieldsCallback() {
        @Override
        public void onTicketsFieldsLoaded(DeskTicketFieldList response) {
              Log.i("APITEST", "getTicketsFieldsList success");
        }
        @Override
        public void onException(DeskException exception) {
              Log.i("APITEST", "getTicketsFieldsList exception "+exception.getErrorMsg());
         }
  }, departmentId);
}
To include a file attachment in the ticket, use the following method.
MyApplication.deskInstance.uploadAttachment(new DeskCallback.DeskUploadAttachmentCallback() {
      @Override
      public void onUploadSuccess(DeskUploadAttachmentResponse response) {
            Log.i("APITEST", "uploadAttachment success "); 
      }
      @Override
      public void onException(DeskException exception) {
            Log.i("APITEST", "uploadAttachment exception "+exception.getErrorMsg());
      }
}, fileTobeuploaded);

Knowledge Base

These methods help you display your knowledge base and all associated content on the ASAP add-on.
Category deeplinking
The following method displays the list of categories/sub-categories in your knowledge base and the help articles under each category.
MyApplication.deskInstance.startKBCategory(activity, permalink);
  • Activity is the instance of the activity.
  • Permalink is the URL of the knowledge base category.

For instance, in the URL in the image above, the portion following "/kb/" is the permalink of the category. You can pass this portion as the path of the category or sub-category.
Article deeplinking
The following method displays the content of a help article right within your ASAP add-on.
MyApplication.deskInstance.startKBArticle(activity, permalink);
  1. Activity is the instance of the activity.
  2. Permalink is the URL of the help article.

For instance, in the URL in the image above, the portion following "/articles/" is the permalink of the article.

Community

These methods help you display your user community and all associated content on the ASAP add-on.
Custom-Configuring Community Actions
Users can perform a range of actions, including editing and deleting topics; and adding, editing, and deleting comments, in the community module.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the community through the ASAP add-on.
ZDeskCommunityConfiguration communityConfiguration = new ZDeskCommunityConfiguration();
communityConfiguration.setTopicEditAllowed(false);
communityConfiguration.setTopicDeleteAllowed(false);
communityConfiguration.setReplyEditAllowed(false);
MyApplication.deskInstance.setCommunityConfiguration(communityConfiguration);
Getting the Most Popular Topics
The following API fetches the forum topics with the most number of likes.
MyApplication.zohoDeskPortalSDKInstnace.getMostPopularTopics(new DeskCallback.DeskCommunityTopicsListCallback() {
   @Override
   public void onTopicsListCompleted(DeskTopicsList response) {
       Log.i("APITEST", "success");
   }
   @Override
   public void onException(DeskException exception) {
       Log.i("APITEST", "exception");
   }
}, categoryId, type, from, limit, includeCount);
Params
  1. DeskCallback.DeskCommunityTopicsListCallback is the callback object.
  2. categoryId - long - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value "-1". 
  3. type - string - Type of forum topic. Values allowed are: QUESTIONIDEAANNOUNCEMENTPROBLEM, and DISCUSSION.
  4. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  5. limit - int - Number of topics to fetched
  6. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not
Getting the Most Discussed Topics
The following API fetches the forum topics with the most number of comments.
MyApplication.zohoDeskPortalSDKInstnace.getMostDiscussedTopics(new DeskCallback.DeskCommunityTopicsListCallback() {
    @Override
    public void onTopicsListCompleted(DeskTopicsList response) {
        Log.i("APITEST", "success");
    }

    @Override
    public void onException(DeskException exception) {
        Log.i("APITEST", "exception");
    }
}, categoryId, type, from, limit, includeCount);
Params
  1. DeskCallback.DeskCommunityTopicsListCallback is the callback object.
  2. categoryId - long - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value "-1". 
  3. type - string - Type of forum topic. Values allowed are: QUESTIONIDEAANNOUNCEMENTPROBLEM, and DISCUSSION.
  4. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  5. limit - int - Number of topics to fetch
  6. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not

Tickets

These methods help you configure the submit ticket form the way you want, on the ASAP add-on.
Hiding Fields in the Submit Ticket Form
The Submit Ticket form in your ASAP add-on displays the same fields configured in the ticket layout in your Zoho Desk portal. If you want to hide any of the fields in the form, you can do so using the setTicketsFieldsListTobeShown() method. 
You must pass the list of fields (apiNames) as strings in this method. You might also have to pass the departmentId key, depending on the department mapping of the add-on. For instance, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-ticket fields mapping in the Submit Ticket form. 
After you include this method, the form displays only the fields you passed in the method. However, keep in mind that mandatory fields will not be hidden even if you do not pass their names in the method.
Hiding Mandatory Fields in the Submit Ticket Form
If you absolutely want to hide a mandatory field in the form, you can do so, provided the value of the field is pre-filled. To do this, you must use the preFillTicketFields() method.
The preFillTicketFields() method proves useful when you want to pre-populate fields with values, such as auto-generated IDs or OS version of devices.
To use this method, you must pass the list of PreFillTicketField objects. You should also pass the departmentId key, depending on the department mapping of the add-on.
Just like in the case of the setTicketsFieldsListTobeShown() method, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-fields mapping. 
The PreFillTicketField object contains three main properties:
  1. fieldApiName - string - apiName of the ticket field. You can retrieve the apiName of each field using the getTicketFields() method.
  2. fieldValue - object
    • For multiselect fields, pass the values allowed, as a list of strings.
    • For pick list fields, pass one of the values allowed, as a string.
    • For date fields, pass the value as a string in the dd-MM-yyyy format.
    • For dateTime fields, pass the value as a string in the dd-MM-yyyy HH:mm a format.
    • For Boolean fields, pass a Boolean value.
    • For all other field types, pass the values as string objects.
    • Make sure that the values you pass adhere to the maxlength and decimal restrictions defined for the field.
  3. isEditable - Boolean - Key that defines if the value in the field is editable or not
Note: For more clarity, refer to the sample code here.
Custom-Configuring Ticket Actions
Users can perform a range of actions, including replying to, commenting on, and closing tickets.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the ticket submission screen on the ASAP add-on.
ZDeskTicketConfiguration ticketConfiguration = new ZDeskTicketConfiguration();
ticketConfiguration.setReplyAllowed(false);
ticketConfiguration.setTicketUpdateAllowed(false); //Ticket update will affect for Ticket close and Priority update
ticketConfiguration.setCommentAllowed(true);
ticketConfiguration.setCommentEditAllowed(false);
ticketConfiguration.setCommentDeleteAllowed(false);
MyApplication.deskInstance.setTicketConfiguration(ticketConfiguration);

Others

These methods help you perform a variety of other actions in your ASAP add-on.
Updating User Details
The following API helps update the details of users added to your help desk portal.
HashMap<String, String> profileData = new HashMap<>();
profileData.put("displayName", "displayName");
profileData.put("mobile", "123456");
MyApplicaiton.zohoDeskPortalSDKInstnace.updateProfile(profileData, new DeskCallback.DeskUpdateProfileCallback() {
    @Override
    public void onProfileUpdated(JSONObject jsonObject) {
        Log.i("UpdateProfile", "Success");
    }

    @Override
    public void onException(final DeskCallback.DeskException exception) {
        Log.i("UpdateProfile", "Exception");
    }
});
Params
  1. HashMap <String, String> data - Key and value pair. Keys included are: twitter, phonefacebooknamedisplayNamemobilecountryLocale, and timeZone
  2. DeskCallback.DeskUpdateProfileCallback - Callback object

SDK Logging

The ASAP SDK also provides you with the option to fix errors that occur while using the add-on. This is made possible by SDK logging.
To enable logging for the SDK, include the following code snippet.
ZohoDeskPortalSDK.Logger.enableLogs();
After enabling SDK logging, you can check the console log for the errors and take necessary action.
Note: Some debug information related to the SDK is stored in logcat. Therefore, make sure that enableLogs() does not exist in the release build.

Release Notes

v1.1.4
  • Introduced an API that helps update user details. For more details click here.
  • Added the provision to enable/disable user actions in the ticket submission screen. For more details, click here
v1.1.3
  • Fixed an issue that caused logout failure in some cases.
v1.1.2
  • Started displaying the permission dialog during users' first attempt to access phone storage through the app/add-on.
v1.1.1
  • Fixed issues identified.
v1.1.0
  • Introduced methods that help custom-configure the fields in the Submit Ticket screen. For more details, check here.
  • Included the All option in the sub-forum filter in the Community module.
  • Enabled deep-linking for knowledge base categories. For more details, check here.
  • Added the provision to enable/disable user actions in the Community module. For more details, check here.
v1.0.1
  • Added the Discussion topic type to the Community module.
  • Fixed an issue related to the search functionality in the Community module. (If you are a new user starting out with this version of the SDK, you do not have to make any changes to overcome this issue. But if you are upgrading from the previous version of the SDK and have enabled JWT-based authentication in your Zoho Desk portal, make sure to regenerate the user token after upgrading. Check here in the demo application. No functionality or features will be impacted for end-users.)
v1.0
  • Introduced rich text formatting for ticket comments.
  • Implemented threaded comments for forum topics in the user community.
  • Implemented comment actions for comments on forum topics.
  • Implemented search feature within the user community.
  • Introduced event callbacks. For more deatils, check here.
  • Added APIs related to community categories, most popular topics, and most discussed topics. For more details, check here.
  • Added a method that launches the topic detail screen when a topic ID is passed.
v0.826.1
  • Added the Follow option for categories in the Community module. This option will be displayed only for authenticated users.
v0.826
  • Fixed an issue that caused an app crash if the app contained the androidx dependency.
v0.825
  • Enabled support for the Indian data center. To host your ASAP add-on on this datacenter, pass the value of the data center key as DataCenter.IN while initializing the SDK.
  • Included a new method that launches the add-on dashboard with its configuration overridden. For more details, check here
  • Added the from and limit parameters to the API related to products. The from parameter denotes the index number of the resource and the limit parameter denotes the number of resources to return. If these two parameters are not passed in the API request, the first 10 products are returned, by default.
v0.824
  • Enabled push notifications for the following ticket actions:
    • Agent creates a ticket on behalf of the user.
    • Agent sends a new ticket response.
    • Priority of the ticket is changed.
    • Status of the ticket is changed.
    • A new comment is added to a ticket.
    • A ticket comment is edited.
  • Introduced a callback method for the Submit Ticket screen. Through this method, the ASAP add-on can be configured such that ticket details are sent to the app immediately after a ticket is submitted.
v0.823
  • Fixed an issue that caused an app crash if the user tried to load Knowledge Base articles that exceeded 2 MB in size.
v0.822
  • Rectified a critical configuration issue that gave other apps access to files stored in the internal directory of apps containing the Zoho Desk Portal SDK.

Migrating from v1.x to v2.0

Integrating the SDK with Your Android App

In late 2018, Zoho Desk introduced a capability called ASAP, which takes help to users proactively, eliminating the hassle of navigating to a different tab and finding help resources. Using the ASAP SDK, you can embed a widget into your Android app, so that your customers can reach you quickly for support.

Over these two years, we have refined the ASAP SDK and made it more accessible and easier to use. The culmination of these refinements is here for you. Presenting to you the ASAP SDK for Android - v2.0!

If you have already been using the ASAP SDK with your Android app, there is a bit of migration that you would need to do to make your app compatible with v2.0.

The following tables list the changes you need to make to ensure a smooth migration.
v1.0 Series
v2.0
In the older version, you would integrate the entire asapsdk (com.zoho.desk:asapsdk)
Starting from v2.0, you can select the help modules, based on our requirements.
com.zoho.desk:asapsdk - All help modules: Tickets, Knowledge Base, Community, and Live Chat
com.zoho.desk:asap - Only the Tickets, Knowledge Base, and Community modules
com.zoho.desk:asap-api - Serves as the API Provider for the ASAP SDK. This option does not include a UI. So, if your app handles the UI part and needs just contact with the server, you can choose this option.

Build Configuration details

v1.0 Series
v2.0
  • compileSdkVersion - 28
  • buildToolsVersion - 28.0.3
  • supportLibVersion - 26.1.0
  • minSdkVersion - 16
  • targetSdkVersion - 28
  • compileSdkVersion - 29
  • buildToolsVersion - 29.0.0
  • supportLibVersion - 27.1.1
  • minSdkVersion - 16
  • targetSdkVersion - 29

Initialization Code

v1.0 Series
v2.0
initDesk method contains 4 parameters:
  1. orgId
  2. appId
  3. DC
  4. configuration object
MyApplication.deskInstance.initDesk(orgId, appId, dcVal, config);
initDesk method contains 3 parameters:
  1. orgId
  2. appId
  3. DC
MyApplication.deskInstance.initDesk(orgId, appId, dcVal);

Displaying Help Components

Method for displaying the Desk Home Screen
v1.0 Series
v2.0
MyApplication.deskInstance.startDeskHomeScreen(activity);
ZDPortalHome.show(activity);
Method for displaying the Desk Home Screen with custom configuration
v1.0 Series
v2.0
MyApplication.deskInstance.startDeskHomeScreen(activity, config);
ZDPortalHome.show(activity, config);
Method for displaying the Help Center (Knowledge base)
v1.0 Series
v2.0
MyApplication.deskInstance.startHelpCenter(activity);
ZDPortalKB.show(activity);
Method for displaying the Community module
v1.0 Series
v2.0
MyApplication.deskInstance.startCommunity(activity);
ZDPortalCommunity.show(activity);
Method for displaying the Submit Ticket screen
v1.0 Series
v2.0
MyApplication.deskInstance.startNewTicket(activity);
ZDPortalSubmitTicket.show(activity);
Method for displaying the Submit Ticket with a callback
v1.0 Series
v2.0
MyApplication.deskInstance.startNewTicket(activity, callBack);
ZDPortalSubmitTicket.show(activity, callback);
Method for displaying the My Tickets list
v1.0 Series
v2.0
MyApplication.deskInstance.startTickets(activity);
ZDPortalTickets.show(activity);
Method for displaying the Live Chat module
v1.0 Series
v2.0
MyApplication.deskInstance.startLiveChat(activity);
ZDPortalChat.show(activity);

Authenticating Users in the SDK

v1.0 Series
v2.0
MyApplication.deskInstance.setUserToken(userToken, callback);
where callback is an instance of DeskCallback.DeskSetUserCallback
MyApplication.deskInstance.setUserToken(userToken, callback);
where callback is an instance of ZDPortalCallback.SetUserCallback

Logging Users out from the SDK

v1.0 Series
v2.0
MyApplication.deskInstance.removeUser(callBack);
where callback is an instance of DeskCallback.DeskRemoveUserCallback
MyApplication.deskInstance.logout(callBack);
where callback is an instance of ZDPortalCallback.LogoutCallback

Customizing the Add-On UI

v1.0 Series
v2.0
MyApplication.deskInstance.setThemeResource(themeResourceId);
ZDPortalConfiguration.setThemeResource(themeResourceId);

Changing Language Settings

v1.0 Series
v2.0
DeskConfig config = new DeskConfig.Builder().setLanguage("es").build();
MyApplication.deskInstance.initDesk(orgId, appId, dc, config);
ZDPortalConfiguration.setLanguage("es");

Enabling Notifications

Method for handling Push Notifications
v1.0 Series
v2.0
MyApplication.deskInstance.handleNotification(context, remoteMsgData, icon);
ZDPortalConfiguration.handleNotification(context, remoteMsgData, icon);

Programmatically Adding Tickets

Method for posting tickets (Submit Ticket API)
v1.0 Series
v2.0
MyApplication.deskInstance.addTicket(ticketData, new DeskCallback.DeskAddGuestTicketCallback() {
  @Override
  public void onTicketAdded() {
}
  @Override
  public void onException(DeskException exception) {
}
});
where ticketData is an instance of DeskNewTicketData
and callback is an instance of DeskCallback.DeskAddGuestTicketCallback
ZDPortalTicketsAPI.createTicket(new CreateTicketCallback() {
  @Override
  public void onTicketCreated(Ticket ticket) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, ticketData, params);
where ticketData is an instance of HashMap<String, Object>
and callback is an instance of ZDportalCallback.CreateTicketCallback
Method for fetching list of departments (Departments API Provider)
v1.0 Series
v2.0
MyApplication.deskInstance.getDepartmentsList(new DeskCallback.DeskDepartmentsCallback() {
  @Override
  public void onDepartmentsLoaded(DeskDepartmentsList response) {
}
  @Override
  public void onException(DeskException exception) {
}
});
where callback is an instance of DeskCallback.DeskDepartmentsCallback
ZDPortalAPI.getDepartments(new ZDPortalCallback.DepartmensCallback() {
  @Override
  public void onDepartmentsDownloaded(DepartmentsList departmentsList) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, params);
where callback is an instance of DeskCallback.DeskDepartmentsCallback
and params is an instance of HashMap<String, String>
Method for fetching the list of Products (Products List API Provider)
v1.0 Series
v2.0
MyApplication.deskInstance.getProductsList(new DeskCallback.DeskProductsCallback() {
  @Override
  public void onProductsCompleted(DeskProductsList response) {
}
  @Override
  public void onException(DeskException exception) {
}
}, departmentId,1,10);
where callback is an instance of DeskCallback.DeskProductsCallback
deptId - ID of the department
from - Index number, starting from which
the products must be listed
limit - Number of products to fetch
ZDPortalAPI.getProductsList(new ProductsCallback() {
  @Override
  public void onProductsDownloaded(ProductsList productsList) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, params);
where callback is an instance of ZDPortalCallback.ProductsCallback
and params is an instance of HashMap<String, String>
Method for fetching the List of Ticket Fields (Ticket Fields API Provider)
v1.0 Series
v2.0
MyApplication.deskInstance.getTicketsFieldsList(new DeskCallback.DeskTicketsFieldsCallback() {
  @Override
  public void onTicketsFieldsLoaded(DeskTicketFieldList response) {
}
  @Override
  public void onException(DeskException exception) {
}
}, deptId);
where callback is an instance of DeskCallback.DeskTicketsFieldsCallback deptId - long (id of the department)
ZDPortalTicketsAPI.getTicketFields(new TicketFieldsCallback() {
  @Override
  public void onTicketFieldsDownloaded(TicketFieldsList ticketFieldsList) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, params, featureFlag);
where callback is an instance of ZDPortalCallback.TicketFieldsCallback
and params is an instance of HashMap<String, String>
featureFlag - instance of String (for example, "apiName")
Method for uploading attachments (Upload Attachments API Provider)
v1.0 Series
v2.0
MyApplication.deskInstance.uploadAttachment(new DeskCallback.DeskUploadAttachmentCallback() {
  @Override
  public void onUploadSuccess(DeskUploadAttachmentResponse response) {
}
  @Override
  public void onException(DeskException exception) {
}
}, fileTobeuploaded);
where callback is an instance of DeskCallback.DeskUploadAttachmentCallback
fileTobeUploaded - instance of File object
ZDPortalTicketsAPI.uploadAttachment(new UploadAttachmentCallback() {
  @Override
  public void onAttachmentUploaded(ASAPAttachmentUploadResponse response) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, fileTobeUploaded, params);
where callback is an instance of ZDPortalCallback.UploadAttachmentCallback
and params is an instance of HashMap<String,String>
fileTobeUploaded - instance of File object

Knowledge Base

Method for deep-linking a knowledge base category
v1.0 Series
v2.0
MyApplication.deskInstance.startKBCategory(activity, permalink);
ZDPortalKB.showCategoryWithPermalink(activity, permaLink);
Method for deep-linking a knowledge base article
v1.0 Series
v2.0
MyApplication.deskInstance.startKBArticle(activity, permalink);
ZDPortalKB.showArticleWithPermalink(activity, permaLink);

Community

Method for configuring user actions in the Community
v1.0 Series
v2.0
MyApplication.deskInstance.setCommunityConfiguration(communityConfiguration);
communityConfiguration - instance of ZDeskCommunityConfiguration
ZDPortalCommunity.setConfiguration(communityConfiguration);
communityConfiguration - instance of ZDPortalCommunityConfiguration
Method for fetching the most popular topics (Most Popular Topics API Provider)
v1.0 Series
v2.0
MyApplication.zohoDeskPortalSDKInstnace.getMostPopularTopics(new DeskCallback.DeskCommunityTopicsListCallback() {
  @Override
  public void onTopicsListCompleted(DeskTopicsList response) {
}
  @Override
  public void onException(DeskException exception) {
}
}, categoryId, type, from, limit, includeCount);
where callback is an instance of DeskCallback.DeskCommunityTopicsListCallback
categoryId - long (id of the Community category)
type - instance of String (type of the topics)
from - int from index
limit - int number of topics
includeCount - boolean
ZDPortalCommunityAPI.getMostPopularTopics(new ZDPortalCallback.CommunityTopicsCallback() {
  @Override
  public void onCommunityTopicsDownloaded(DeskTopicsList deskTopicsList) {
}
  @Override
  public void onException(ZDPortalException e) {
}
}, params);
where callback is an instance of ZDPortalCallback.CommunityTopicsCallback
and params is an instance of HashMap<String, String>
Method for fetching the most discussed topics (Most Discussed Topics API Provider)
v1.0 Series
v2.0
MyApplication.zohoDeskPortalSDKInstnace.getMostDiscussedTopics(new DeskCallback.DeskCommunityTopicsListCallback() {
  @Override
  public void onTopicsListCompleted(DeskTopicsList response) {
}
  @Override
  public void onException(DeskException exception) {
}
}, categoryId, type, from, limit, includeCount);
where callback is an instance of DeskCallback.DeskCommunityTopicsListCallback
categoryId - long (id of the Community category)
type - instance of String (type of the topics)
from - int from index
limit - int number of topics
includeCount - boolean
ZDPortalCommunityAPI.getMostDiscussedTopics(new ZDPortalCallback.CommunityTopicsCallback() {
  @Override
  public void onCommunityTopicsDownloaded(DeskTopicsList deskTopicsList) {
}
  @Override
  public void onException(ZDPortalException e) {
}
}, params);
where callback is an instance of ZDPortalCallback.CommunityTopicsCallback
and params is an instance of HashMap<String, String>

Tickets

Method for configuring the List of Ticket fields to show in the Submit Ticket form
v1.0 Series
v2.0
MyApplication.deskInstance.setTicketsFieldsListTobeShown(ticketListTobeShown, deptId);
ZDPortalSubmitTicket.setTicketsFieldsListTobeShown(ticketListTobeShown, deptId);
Method for pre-populating values in Ticket fields
v1.0 Series
v2.0
MyApplication.deskInstance.preFillTicketFields(preFillTicketFields, deptId);
ZDPortalSubmitTicket.preFillTicketFields(preFillTicketFields, deptId);
Method for configuring ticket actions
v1.0 Series
v2.0
MyApplication.deskInstance.setTicketConfiguration(ticketConfiguration);
ticketConfiguration - instance of ZDeskTicketConfiguration
ZDPortalTickets.setConfiguration(ticketConfiguration);
ticketConfiguration - instance of ZDPortalTicketConfiguration

Others

Method for updating user information (updateProfile API Provider)
v1.0 Series
v2.0
MyApplicaiton.zohoDeskPortalSDKInstnace.updateProfile(params, new DeskCallback.DeskUpdateProfileCallback() {
  @Override
  public void onProfileUpdated(JSONObject jsonObject) {
}
  @Override
  public void onException(final DeskCallback.DeskException exception) {
} });
where callback is an instance of DeskCallback.DeskUpdateProfileCallback
and params is an instance of HashMap<String, String>
ZDPortalAPI.updateProfileDetails(new ZDPortalCallback.UserDetailsCallback() {
  @Override
  public void onUserDetailsSuccess(DeskUserProfile userProfile) {
}
  @Override
  public void onException(ZDPortalException exception) {
}
}, params);
where callback is an instance of ZDPortalCallback.UserDetailsCallback
and params is an instance of HashMap<String, String>

    Zoho DataPrep Personalized Demo

    If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

    Zoho CRM Training

      Create, share, and deliver

      beautiful slides from anywhere.

      Get Started Now





              Zoho CRM Training Programs

              Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

              Zoho CRM Training

                  Zoho SalesIQ Resources



                      Zoho TeamInbox Resources




                                Zoho DataPrep Resources

                                  Zoho DataPrep Demo

                                  Get a personalized demo or POC

                                  REGISTER NOW


                                    Design. Discuss. Deliver.

                                    Create visually engaging stories with Zoho Show.

                                    Get Started Now











                                                          • Related Articles

                                                          • Working with the ASAP SDK for React Native

                                                            The ASAP SDK for React Native makes help available within quick reach for the end-users of your mobile app. Using this SDK, you can add and customize an add-on that resides within your iOS/Android app and provides end-users with easy access to your: ...
                                                          • Working with the ASAP SDK for iOS

                                                            SDK v2.0 Introduction The ASAP SDK for iOS makes help available within quick reach for the end-users of your iOS app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your: ...
                                                          • Working with the ASAP Add-On for the Web

                                                            Introduction The ASAP add-on for websites makes your help center available within quick reach for your end-customers. By integrating this add-on with your website, you can provide your customers with easy access to your:  Customer support team (to ...
                                                          • Working with the ASAP Extension for Google Chrome

                                                            Introduction The ASAP extension for Google Chrome is a nifty tool that helps you bridge your website with your knowledge base for the benefit of your customers/site visitors. This extension enables you to easily configure tooltips that display ...
                                                          • Working with the ASAP Add-Ons for Mobile Platforms

                                                            The ASAP SDKs for mobile platforms--iOS and Android--make help available within quick reach for the end-users of your mobile apps. Using these SDKs, you can create and customize add-ons that reside within your app and provide end-users with easy ...

                                                          Resources

                                                          Videos

                                                          Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                          eBooks

                                                          Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                          Webinars

                                                          Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                          CRM Tips

                                                          Make the most of Zoho CRM with these useful tips.



                                                            Zoho Show Resources