Hello πŸ‘‹ How can we help?

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

This article provides all the necessary guidelines for migration from the HelpCrunch Android SDK 2.x to the Android SDK 3.x.
Written by Alex
Updated 1 week ago

Introduction

The latest major version of the HelpCrunch Android SDK is v3.

If you're currently using the v2 SDK for your Android application, it is important that you migrate to the v3 SDK so that your app will have all the newest features.

General migration info

  • The Maven repository has changed to avoid conflicts during updates.
  • The new version of the HelpCrunch SDK is not backwards compatible with the prior versions. It has different packages of User, Options, Themes and Callback models and related methods.
  • The HCTheme and related classes have some new and deprecated methods.
  • The following methods no longer require context or applicationContext: HelpCrunch.initialize, HelpCrunch.showChatScreen.
  • The HelpCrunch.showChatScreen now needs more time to initialize, so it has a callback now.
  • The new version has a different localization strings.xml file structure.

Differences between the 2.x version and the newer SDK

Version 3.0.0

The SDK version 3.0.0-beta.01 is the latest major version of our Android SDK. All future development of the API will be based on this version.

Version 2.0.x

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

New v3.0 features:

  • New design
  • Chat customization
  • Better tracking of user events
  • Better tracking of SDK events (SDK screen open/closed, new message arrived, first message sent, following a link) and SDK status
  • Chats lists and new chat creation function
  • Manual chats and targeted chat broadcasts
  • Chat rating
  • Offline message

Migration

Please, check our demo, before we start. One picture's worth a thousand words :)

New packages

After upgrading to the 3.x version, your code editor can light up in red. The thing is, we've changed the packages to better obfuscate the code. Please, remove the old imports and import the new ones.

Version 3.x

//Core
import com.helpcrunch.library.core.Callback;
import com.helpcrunch.library.core.HelpCrunch;
import com.helpcrunch.library.core.options.HCOptions;
import com.helpcrunch.library.core.options.HCPreChatForm;

//UserData
import com.helpcrunch.library.core.models.user.HCUser;

//Theme
import com.helpcrunch.library.core.options.design.HCAvatarTheme;
import com.helpcrunch.library.core.options.design.HCChatAreaTheme;
import com.helpcrunch.library.core.options.design.HCMessageAreaTheme;
import com.helpcrunch.library.core.options.design.HCNotificationsTheme;
import com.helpcrunch.library.core.options.design.HCPreChatTheme;
import com.helpcrunch.library.core.options.design.HCSystemAlertsTheme;
import com.helpcrunch.library.core.options.design.HCTheme;
import com.helpcrunch.library.core.options.design.HCToolbarAreaTheme;

Version 2.x

//Core
import com.helpcrunch.library.core.Callback;
import com.helpcrunch.library.core.HelpCrunch;
import com.helpcrunch.library.options.HCOptions;
import com.helpcrunch.library.options.HCPreChatForm;

//User
import com.helpcrunch.library.core.repository.models.user.HCUser;

//Theme
import com.helpcrunch.library.options.design.HCAvatarTheme;
import com.helpcrunch.library.options.design.HCChatAreaTheme;
import com.helpcrunch.library.options.design.HCMessageAreaTheme;
import com.helpcrunch.library.options.design.HCNotificationsTheme;
import com.helpcrunch.library.options.design.HCPreChatTheme;
import com.helpcrunch.library.options.design.HCSystemAlertsTheme;
import com.helpcrunch.library.options.design.HCTheme;
import com.helpcrunch.library.options.design.HCToolbarAreaTheme;

Initialization

Version 3.x

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

Version 2.x

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)

Open Chat Screen

Version 3.x

Since SDK initialization now takes longer, there may be a situation when a user tries to open a chat before initialization is completed. That's why we've added a callback which tracks the chat opening status.

public static void showChatScreen(@NotNull HCOptions options, @Nullable Callback<Object> callback)

Version 2.x

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

Localization

Version 3.x

New localization keys have been added due to the appearance of some new features.

	<!--Chat Form-->
	<string name="hc_waiting_message">Searching for a free agent. \nPlease hold on.</string>
	<string name="hc_offline_message">Sorry, we\'re offline now πŸ™ˆ Feel free to send all your questions, contact details or feedback right here, and we\'ll get back to you asap πŸ˜‡</string>
	<string name="hc_message_hint">Type message</string>
	<string name="hc_copied">Copied</string>
	<string name="hc_menu_copy">Copy</string>
	<string name="hc_menu_open">Open</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>
	<string name="hc_new_chat_arrived">New chat has arrived</string>

	<!--Chats-->
	<string name="hc_support_team">%s Team</string>
	<string name="hc_support_team_placeholder">Support Team</string>
	<string name="hc_error_no_chats_found">No chats found</string>

	<!--Chat-->
	<string name="hc_attachment_video">Video</string>
	<string name="hc_attachment_file">File</string>
	<string name="hc_attachment_image">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>
	</plurals>

	<string name="hc_download_file_title">Download file?</string>
	<string name="hc_download_ok">Yes</string>
	<string name="hc_download_no">No</string>
	<string name="hc_download_loading_complete">Loading is complete πŸ‘Œ\nSaved to Downloads folderπŸ‘Œ</string>
	<string name="hc_loading">Loading…</string>

	<!--Tech-->
	<string name="hc_you">You</string>
	<string name="hc_someone">Someone</string>
	<string name="hc_tech_client">client</string>
	<string name="hc_tech_chat_rated_poor">Poor</string>
	<string name="hc_tech_chat_rated_average">Average</string>
	<string name="hc_tech_chat_rated_great">Great</string>
	<string name="hc_tech_chat_rating_sent">Please rate this chat</string>
	<string name="hc_tech_chat_rated">Chat rated %s</string>
	<string name="hc_tech_chat_marked_by">Chat marked %s by %s</string>
	<string name="hc_tech_chat_marked_as">Chat marked %s</string>
	<string name="hc_tech_someone_closed_chat">%s closed this chat</string>

	<!--Agent-->

	<string name="hc_closed">Closed</string>
	<string name="hc_chat_closed">This chat is closed</string>

	<string-array name="hc_chat_statuses">
		<item>New</item>
		<item>Open</item>
		<item>Pending</item>
		<item>On-hold</item>
		<item>Closed</item>
	</string-array>

	<!--Notifications-->
	<string name="hc_notification_channel_text">Allow Support 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_pre_chat_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_pre_chat_error_required">%s is required</string>
	<string name="hc_pre_chat_error_pattern">%s is not valid</string>

	<!--In App Errors -->
	<string name="hc_error_no_internet_connection">Please, check your internet connection</string>
	<string name="hc_error_handler_unknown">Something went wrong. Please try again later</string>
	<string name="hc_error_chat_deleted">This chat was removed by agent. You\'ll be logged out</string>
	<string name="hc_error_file_size">You can\'t send files bigger than 16 MB.</string>
	<string name="hc_error_file_cant_open">Can\'t open this file</string>
	<string name="hc_error_no_camera_exists">No Application exists for camera!</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_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_menu_item_file">File</string>
	<string name="hc_share">Share…</string>
	<string name="hc_debug">Debug</string>
	<string name="hc_send_intent_title">Send to:</string>

	<!--Rating View-->
	<string name="hc_rating_title">How do you rate your customer service experience?</string>
	<string name="hc_chat_rating_values_poor">Poor</string>
	<string name="hc_chat_rating_values_average">Average</string>
	<string name="hc_chat_rating_values_great">Great</string>
	<string name="hc_view_article">View article</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>
	</plurals>

	<!--Notifications-->
	<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>

SDK state tracking

The 3.x version now has the ability to track the SDK state. It's done with the help of the BroadcastReceiver class. Apply new IntentFilter(HelpCrunch.STATE) to use this feature.

All the available states are contained in the HelpCrunch.State enum class. The class currently contains the following values:

  • IDLE - the SDK is waiting for initialization call
  • READY - the SDK is ready
  • LOADING - the SDK is initializing
  • ERROR_BLOCKED_USER - user has been blocked or deleted
  • ERROR_INITIALIZATION - an error occurred while initializing the SDK. It is recommended to check the network connection and the validity of the data for initialization.
  • ERROR_UNKNOWN - an error has occurred, but there is no way to determine its cause.
  private BroadcastReceiver hcStateBroadcastReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            HelpCrunch.State state = (HelpCrunch.State) intent.getSerializableExtra(HelpCrunch.STATE_TYPE);

           if (state != null) {
                Log.d("HcState", state.name());
            }
        }
    };

registerReceiver(hcStateBroadcastReceiver, new IntentFilter(HelpCrunch.STATE));

You can check the status of the SDK at any time using the HelpCrunch.getState() method.

Chat customization

In the new SDK v3.x, the types of the HCTheme were moved to a separate enumeration class called HCTheme.Type. This results in the following changes:

Version 3.x

new HCTheme.Builder(HCTheme.Type.DEFAULT)
//or
new HCTheme.Builder(HCTheme.Type.DARK)
//or you can use Builder with custom color and shouldPaintIconsAutomatically flag
new HCTheme.Builder(R.color.main_color, true)

Deprecated methods

HCSystemAlertsTheme

Method Replace with
setDialogAcceptButtonDrawableRes Unused. Will be removed
setDialogCancelButtonDrawableRes Unused. Will be removed

HCChatAreaTheme

Method Replace with
setFabDownBackgroundRes setFabDownBackgroundColor

HCMessageAreaTheme

Method Replace with
setButtonTextColor setButtonTextColorStateList

Version 2.x

new HCTheme.Builder(HCTheme.DEFAULT)
//or
new HCTheme.Builder(HCTheme.DARK)
//or you can use Builder with custom color and shouldPaintIconsAutomatically flag
new HCTheme.Builder(R.color.main_color, true)

Image loading

In the 3.x versions, we abandoned the Glide API for image loading and started using Coil instead.

If you've configured the SVG files support using glide api generation before, you can remove this code from the new versions. From now on, SVG images are supported by default.

Conclusion

I hope that your migration will be easy and successful. In any case, we will always help you in our support chat πŸ’ͺ☺️

Did this answer your question?