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.

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

Demo application

Before you start reading this long documentation we recommend you to check our demo application as it can answer most of your qustions. You can find it here:

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
    implementation ('com.helpcrunch:helpcrunch-sdk:1.5.2') { transitive=true } 

    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. It is important. Add a File Provider to share media files:

    <?xml version="1.0" encoding="utf-8"?>
        <external-files-path name="external_files" path="."/>
        <external-files-path name="my_images" path="my_images" />
  5. To show the HelpCrunch UI after you have initialized it, simply call the showChatScreen helper method on HelpCrunch:

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

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 projectCreate 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 appIt’s quite simple – you just need to enter android package name and Firebase will figure out all other fields:
    Enter your android package name
  1. Then you need to add Firebase implementation to your Gradle build file:
    Add firebase to gradle build file
  2. 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
  3. 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

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:

HelpCrunchOptions opts = new HelpCrunchOptions()

HelpCrunch.initializeWithOptions(this, YOUR_HELPCRUNCH_SUBDOMAIN, YOUR_APP_ID, YOUR_APP_SECRET, opts); 

Saving app user data to HelpCrunch is done by calling HelpCrunch.updateUser(Context context, 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 user = new UserBuilder()
HelpCrunch.updateUser(context, user, callback);

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 chatIn 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<String, Object> custom = new HashMap<String, Object>();
custom.put("CUSTOM_TIME", System.currentTimeMillis());
custom.put("CUSTOM_FLAG", true);
custom.put("CUSTOM_STRING", "searchText");
custom.put("CUSTOM_NUMBER", 1586);

User user = new UserBuilder()
HelpCrunch.updateUser(context, user, callback);

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 searchYou can get app user data from HelpCrunch by calling

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

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) {


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>
<string name="helpcrunch_chat_welcome_message">"Your suggestions, ideas or complaints greatly help us. We'll get back to you pretty soon!"</string>
<string name="helpcrunch_permissions_ok">OK</string>
<string name="helpcrunch_permissions_cancel">Cancel</string>
<string name="helpcrunch_permissions_content">Allow file system access to improve file sharing</string>

Customizing push notifications view

You can customize the view of push notifications sent by HelpCrunch android SDK by changing the notification icon and text.

  1. Add your app icon to “drawable”
  2. Add your notification channel title
  3. Add large icon color
  4. Set up the SDK, indicating which resource to use:
    HelpCrunchOptions options = new HelpCrunchOptions()
            .setNotificationsChannelTitle("Channel Title")
    HelpCrunch.initializeWithOptions(this, ORGANIZATION, APP_ID, SECRET, options);

Changing users

If you use user authentication in your application and you want start a new chat or change a user you can use logout method:

HelpCrunch.logout(new Callback() {
  public void onSuccess(Void result) {

  public void onError(Exception e) {