Android SDK

This tutorial provides you with a step-by-step guide to configuring your Android SDK in your mobile application.

We will start on configuring your app in your HelpCrunch profile, then proceed to implementing and configuring HelpCrunch SDK in your Android project, and finally, we’ll describe how to create a push-enabled Android application.

1. Configuring app on your HelpCrunch profile

Create a new app

To add a new app, login into your HelpCrunch account, then go to the Settings pageSet up & CustomizeAndroid APPs and press “Add new”. Fill the Android App Name field and press “Apply” button:
Android Apps

2. Adding SDK to your project

You can add HelpCrunch SDK to your Android application with Gradle or Maven build systems.

  1. Add the following code to your Gradle file compile

    compile ('com.helpcrunch:helpcrunch-sdk:1.+@aar') {
    or Maven

  2. For the next step you’ll need the Android Initialization Code. You can copy this code on apps list in your HelpCrunch account (Settings pageSet up & CustomizeAndroid APPsYour app nameAndroid Initialization Code)
    Android Application Code
  3. Initialize the Helpcrunch in your custom application class with your Android Initialization Code

    In your IDE it would look like this:
    Add new java classNew class popup
  4. To show the HelpCrunch UI after you have initialized it, simply call the showChatScreen helper method on HelpCrunch:

    HelpCrunch.showChatScreen(Context context)
  5. After you have called the method it will look like this:
    Android App

3. Enable Push Notifications (optional)

We believe that push notifications are a great way to add real-time messaging to your application and inform your app users that there is a new message came from HelpCrunch server (i.e. from your admin dashboard). It allows you to stay in touch with your users even when the application is not in the foreground. Although, HelpCrunch Mobile SDK does not necessarily require the implementation of push notifications and end users of your application will still be able to receive messages, but in this case, the end users will discover that new messages arrived only after opening HelpCrunch page.

So to add push notifications to your app, you’ll need:

  1. Create or import a Firebase project:
    Create or import a Firebase project

    Create a Firebase project

  2. Add Firebase to a Google project:
    Add Firebase to Google project
  3. Add Firebase to your application (just follow the firebase instructions):
    Add Firebase to your app

    It’s quite simple – you just need to enter android package name and Firebase will figure out all other fields:
    Enter your android package name

  4. Then you need to add

    compile ''
    to your Gradle build file:
    Add firebase to gradle build file
  5. You’ll need a legacy server key to push notifications to work. You can copy in FirebaseSettingsCloud MessagingLegacy Server Key:
    Get Firebase cloud messaging Legacy Server Key
  6. Past the key to “Firebase / GSM API Key” field in your Android application settings at your HelpCrunch admin account (Settings pageSet up & CustomizeAndroid APPsYour app name):
    Firebase / GSM API Key field

4. App Users

By default HelpCrunch SDK requires a user to enter his name before sending messages. You can disable this with initializing Helpcrunch with custom options:

HelpCrunch.Options opts = new HelpCrunch.Options();
opts.requestName = false;

Saving app user data to HelpCrunch is done by calling HelpCrunch.updateUser(User user, Callback callback).
Be sure to put a unique User ID string in withUserID method for all your users. Constructing empty users with no data will not work (you can have no use of an empty user you cannot identify after all).

User c = new UserBuilder()

After you have added user’s data and called updateUser(c) it’s data will appear in your HelpCrunch admin account in chat with that user:
Sent User data in chat

In addition to user’s name / email / and ID HelpCrunch lets you send custom data/attributes of your customers. With the custom data you can send any information about users you wish to track. Send Map<String, Object> containing key/value pairs of number, string or boolean data. This feature will only work if you have constructed a user with UserID:

Map custom = new HashMap();
custom.put("CUSTOM_TIME", System.currentTimeMillis());
custom.put("CUSTOM_FLAG", true);
custom.put("CUSTOM_STRING", "searchText");
custom.put("CUSTOM_NUMBER", 1586);
HelpCrunch.updateUser(new UserBuilder()
.build(), null);

Custom data parameters will appear in chat with user at your HelpCrunch admin account just as same as main user attributes (name, email, user id):
Custom data in chat

Also you will be able to search through your users by custom data you at the “Contacts” page. There 3 types of custom data you can search by: integers, strings and boolean:
Custom data search

You can get app user data from HelpCrunch by calling

User user = HelpCrunch.getStorage().loadUser();

5. Unread messages

You can get a quantity of current chat’s unread messages (for example for displaying on the app icon) by calling this method:

HelpCrunch.getUnreadMessagesCount(new Callback() {
public void onSuccess(MessagesCountResponse result) {
int unreadMessagesCount = result.getMessagesCount();
public void onError(Exception e) {

6. Localization

To localize chat in your application or to change its text, you will need to add string resources with this names to strings.xml of your application:

<string name="helpcrunch_message_hint">Type message</string>
<string name="helpcrunch_enter_name">Enter your name</string>
<string name="helpcrunch_notification_title" translatable="false">HelpCrunch</string>
<string name="helpcrunch_dialog_label" translatable="false">HelpCrunch</string>
<string name="new_message">New message</string>
<string name="helpcrunch_empty_message">Could you please enter your message?</string>
<string name="helpcrunch_empty_user_name">Username is empty</string>
<string name="help_crunch_ok">Ok</string>
<string name="helpcrunch_messages_get_error"><![CDATA[Unable to get messages. Please check your network connection and <b><u>try again</u></b>]]></string>
<string name="helpcrunch_messages_send_error"><![CDATA[Your message was not sent. Please check your network connection and <b><u>try again</u></b>]]></string>
<string name="helpcrunch_user_update_error"><![CDATA[Your user was not updated. Please check your network connection and <b><u>try again</u></b>]]></string>