Hello 👋 How can we help?

Migrate from the Android SDK 1.x to 2.x

This article provides a set of guidelines for migration from the HelpCrunch Android SDK 1.x to the Android SDK 2.x.
Written by Alex
Updated 2 weeks ago

If you're currently using the older version of the HelpCrunch Android SDK, you can find its documentation here. We recommend you to switch to the newer version as soon as possible, though.


If you currently use the v1.x SDK for your Android application, it is important that you migrate to the Android SDK v2.x so that your app will get all the newest important features.

General migration info

  • The new version of the SDK is not backwards compatible with prior versions. It has different User, Options and Callback models and related methods.
  • The new version has a different localization strings.xml file structure.
  • The Maven repository has changed to avoid conflicts during updates.

Differences between the 1.x version and the newer SDK

Version 2.0.0

The SDK version 2.0.0 is the latest major version of our Android SDK. All future development of the API will be done on this version.

Version 1.5+

The SDK version 1.5+ has the v2-based API. It is deprecated and will not be developed further.

New v2.0 features:   

  • New design
  • Chat customization
  • Dark mode
  • Customizable pre-chat forms
  • User's events tracking
  • SDK events tracking (SDK screen open/closed, new message arrived, first message sent, following a link)
  • Easier integration with FCM.


Almost all functions in the new SDK support method overloading.

Models' changes

v1.x v2.x
User HCUser
HelpCrunchOptions HCOptions
HelpCrunchDesign HCTheme
MessageArea HCMessageAreaTheme
HelpCrunchButton  deleted
UserBuilder HCUser.Builder


Version 1.x

In older versions, there was a need to call different initialization methods depending on parameters (initialize or initializeWithOptions)

public static void initialize(Context ctx, String organisation, int appId, String secret)
public static void initialize(Context ctx, String organisation, int appId, String secret, Callback callback)
public static void initializeWithOptions(Context ctx, String organisation, int appId, String secret, HelpCrunchOptions opts)
public static void initializeWithOptions(Context ctx, String organisation, int appId, String secret, HelpCrunchOptions opts, User user)
public static void initializeWithOptions(Context ctx, String organisation, int appId, String secret, HelpCrunchOptions opts, User user, Callback callback)

Version 2.x

Initialization in the new SDK versions occurs through the method initialize overloading.

Initialization method's first parameter is Application instead of Context because the SDK needs a global context for notifications, EmojiCompat and BroadcastReceiver

public static void initialize(@NotNull Application application, @NotNull String organisation, int appId, @NotNull String secret, @Nullable HCUser user, @NotNull HCOptions options, @Nullable Callback<Object> callback)

Build User model

Version 1.x

Map<String, Object> customData = new HashMap<>();
customData.put("CUSTOM_TIME", System.currentTimeMillis());

HCUser registerUser = new UserBuilder()

Version 2.x

The UserBuilder class was replaced by HCUser.Builder class.

The following methods have been changed in the new version:

  • withUserIDwithUserId
  • withOrganizationwithCompany
HashMap<String, Object> customData = new HashMap<>();
customData.put("CUSTOM_TIME", System.currentTimeMillis());

HCUser registerUser = new HCUser.Builder()

User Data Update

Version 1.x

public static void updateUser(Context context, User user, final Callback<User> callback)

Version 2.x

In new SDK you don't need to pass a Context parametr to the updateUser method.

public static void updateUser(@Nullable HCUser user, @Nullable Callback<HCUser> callback)

Open Chat Screen

Version 1.x

public static void showChatScreen(Context context)
public static void showChatScreen(Context context, Bundle bundle)
public static void showChatScreen(Context context, HelpCrunchOptions options)

Version 2.x

public static void showChatScreen(@NotNull Context context, @NotNull HCOptions options)

Get UserData

Version 1.x

In older versions of the SDK, you should get the Storage instance to load user data.


Version 2.x

In new SDK, you do not need to get an instance of the Storage, because the Storage singletone does not exist now. Just call getUser() to get user data model.



Callback class type changed from interface to abstract class

Callback method void onError(Exception e) was replaced by void onError(String message)

Version 1.x

public interface Callback<T> {
    void onSuccess(T result);

    void onError(Exception e);

Version 2.x

public interface Callback<T> {
    void onSuccess(T result);

    void onError(String message);


In the new version, the helpcrunch_ prefix has been replaced with hc_. In addition, new localization keys have been added due to the addition of new features.

Version 1.x

    <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_message_hint">Type message</string>
    <string name="helpcrunch_enter_name">Enter your name</string>
    <string name="helpcrunch_powered">Powered by</string>
    <string name="helpcrunch_dialog_label" translatable="false">HelpCrunch</string>
    <string name="helpcrunch_empty_message">Could you please enter your message?</string>
    <string name="helpcrunch_no_connection_message">Please, check your internet connection</string>
    <string name="helpcrunch_empty_user_name">Username is empty</string>
    <string name="help_crunch_ok">OK</string>
    <string name="helpcrunch_device_not_registered_error">Device is not registered yet!</string>
    <string name="helpcrunch_chat_deleted_error">This chat was removed by agent. You\'ll be logged out</string>
    <string name="helpcrunch_error_something_wrong">Something is wrong. Please, try again later</string>
    <string name="helpcrunch_camera_error">Unfortunately, the camera was not detected</string>
    <string name="select_image">Select image</string>
    <string name="text_show_full">show full message</string>
    <string name="allow_messages_notifications">Allow messages notifications</string>
    <string name="copied">Copied</string>
    <string name="today">Today</string>
    <string name="yesterday">Yesterday</string>
    <string name="sent_at">at</string>

    <string name="helpcrunch_file_size_error">This file is too large</string>

    <string name="helpcrunch_permissions_ok">OK</string>
    <string name="helpcrunch_permissions_cancel">Cancel</string>
    <string name="helpcrunch_permissions_content">Allow file system and camera access to improve file sharing</string>

Version 2.x

	<!--Chat  Form-->
	<string name="hc_waiting_message">Searching for a free agent. Please hold on.</string>
	<string name="hc_message_hint">Type message</string>
	<string name="hc_select_image">Select image</string>
	<string name="hc_copied">Copied</string>
	<string name="hc_menu_copy">Copy</string>
	<string name="hc_menu_open">Open</string>
	<string name="hc_today">Today</string>
	<string name="hc_yesterday">Yesterday</string>
	<string name="hc_sent_at">at</string>
	<string name="hc_permissions_ok">OK</string>
	<string name="hc_permissions_cancel">Cancel</string>
	<string name="hc_permissions_content">Allow file system and camera access to improve file sharing</string>
	<string name="hc_messages_updating">Updating…</string>
	<string name="hc_button_send">Send</string>
	<string name="hc_more_agents">and %d more</string>
	<string name="hc_menu_view_image">View image</string>

	<plurals name="hc_typing">
		<item quantity="zero">typing…</item>
		<item quantity="one">is typing…</item>
		<item quantity="two">are typing…</item>
		<item quantity="few">are typing…</item>
		<item quantity="many">are typing…</item>
		<item quantity="other">are typing…</item>

	<string name="hc_default_notification_title">Help Crunch</string>
	<string name="hc_notification_channel_text">Allow messages notifications</string>

	<!--Pre-Chat Form-->
	<string name="hc_pre_chat_message">Usually we respond immediately. If not, you can expect a reply within a few hours. Please kindly introduce yourself.</string>
	<string name="hc_button_continue">Continue</string>
	<string name="hc_pre_chat_name">Name</string>
	<string name="hc_pre_chat_email">Email</string>
	<string name="hc_pre_chat_company">Company</string>
	<string name="hc_pre_chat_phone_number">Phone number</string>
	<string name="hc_required_error">%s is required</string>
	<string name="hc_pattern_error">%s does not valid</string>

	<!-- In App Errors -->
	<string name="hc_no_internet_connection_error">Please, check your internet connection</string>
	<string name="hc_handler_server_error">Server error. Repeat the request after 5 seconds</string>
	<string name="hc_handler_unknown_error">Something went wrong. Please try again later</string>
	<string name="hc_chat_deleted_error">This chat was removed by agent. You\'ll be logged out</string>
	<string name="hc_file_size_error">You can\'t send files bigger than 16 MB.</string>
	<string name="hc_file_cant_open_error">Can\'t open this file</string>
	<string name="hc_image_load_error">Can\'t load image</string>

	<!--File Picker-->
	<string name="hc_permission_file_picker_rationale">Storage permission is needed to access files.</string>
	<string name="hc_no_files_found">No files found</string>
	<string name="hc_attachments_title_text" formatted="false">(%d/%d)</string>
	<string name="hc_attachments_num" formatted="false">%d</string>
	<string name="hc_picker_title">Select an option</string>
	<string name="hc_select_photo_text">Select a media</string>
	<string name="hc_select_doc_text">Select a document</string>
	<string name="hc_no_camera_exists">No Application exists for camera!</string>
	<string name="hc_videos">Videos</string>
	<string name="hc_images">Images</string>
	<string name="hc_all_photos">All Photos</string>
	<string name="hc_all_videos">All Videos</string>
	<string name="hc_all_files">All Files</string>
	<string name="hc_done">Done</string>
	<string name="hc_menu_item_photo">Photo</string>
	<string name="hc_download">Download</string>
	<string name="hc_downloading">Downloading…</string>
	<string name="hc_downloaded">Downloaded</string>
	<string name="hc_menu_item_file">File</string>
	<string name="hc_share">Share…</string>
	<string name="hc_send_intent_title">Send to:</string>

Keys migration

helpcrunch_chat_welcome_message removed
helpcrunch_message_hint hc_message_hint
helpcrunch_enter_name removed
helpcrunch_dialog_label removed
helpcrunch_empty_message removed
helpcrunch_no_connection_message hc_no_internet_connection_error
helpcrunch_empty_user_name removed
help_crunch_ok removed
helpcrunch_device_not_registered_error removed
helpcrunch_chat_deleted_error hc_chat_deleted_error
helpcrunch_error_something_wrong hc_handler_unknown_error
helpcrunch_camera_error hc_no_camera_exists_error
select_image hc_select_image
text_show_full removed
allow_messages_notifications hc_notification_channel_text
copied hc_copied
today hc_today
yesterday hc_yesterday
sent_at hc_sent_at
helpcrunch_file_size_error hc_file_size_error
helpcrunch_permissions_ok hc_permissions_ok
helpcrunch_permissions_cancel hc_permissions_cancel
helpcrunch_permissions_content hc_permissions_content

Did this answer your question?