Skip to main content

Migration Guide

SDK X is a Hybrid SDK that helps you roll out innovation faster by enabling most of the updates over the air that flow to end users without any downtime or app updates.

Steps to migrate to SDK X

Migrate from legacy SDK to SDK X


Check migration support

Go through migration guide


Update to SDK X

Migrate code/features step by step


Test the migration

Validate the functionality

Unsupported features

We recommend to hold off on SDK X migration if you are currently using the following APIs/features -

These features are yet to be developed, and we may add them to our 2022 roadmap. You can reach out to to raise any query for the above.

Supported SDK Versions

A successful migration indicates maintaining user’s data and chat history when they move from an SDK version to another. We support migration of legacy SDK from version 7+ to SDK X 10.1.+


Migration from SDK version < 6.x

We don’t support the migration from SDK version < 6. If you move to SDK X from version < 6, SDK X will function correctly, but the logged-in user information will be lost, and a new default user will be created. You can log the current user in again, but the corresponding data for that user will not be migrated. It will be treated as a new user in the Helpshift system.

Migrate SDK Gradle Import to SDK X Library

Change the Gradle import statement for Helpshift SDK as following:

dependencies {
implementation ''
implementation 'com.helpshift:helpshift-sdkx:10.1.0'

If you have added design, recyclerview, and cardview dependencies only for Helpshift SDK, then you can remove them because SDK X does not use those libraries.


Remove the legacy SDK dependency from your app. Do not keep both dependencies.

Integration sources other than Gradle are not supported anymore.

For example:

IntelliJ/Eclipse based projects

Maven based projects

Update "install" call

Update the install call as the following.

try {
"<App Id from the Helpshift Dashboard>",
"<Domain name from the Helpshift Dashboard>",
} catch (UnsupportedOSVersionException e) {
// Android OS versions prior to Lollipop (< SDK 21) are not supported.

Please refer to SDK X Getting Started guide for more information.

"install" call Configurations

SDK X’s install API takes in a Map as the configuration for initialization. InstallConfig class has been removed and needs to be replaced by a Map.

Update the configuration passed in the install call based on the following mapping of functions from InstallConfig to a key in Map.

Legacy SDK InstallConfigSDK X : Key in MapExample Value
InstallConfig.Builder.setSupportNotificationChannelId"notificationChannelId""ABC App Channel"
InstallConfig.Builder.setEnableDefaultFallbackLanguageThis config has been removed
InstallConfig.Builder.setFontThis config has been removed
InstallConfig.Builder.disableErrorReportingThis config has been removed

All deprecated configurations have been removed and are not supported anymore.

For more information on configurations, please refer to this document — SDK Configuration - Helpshift SDK X for Android

Conversation and FAQ APIs

Update the public APIs for conversation and FAQs as following.

Support.showConversation(MyActivity.this, apiConfig);
Helpshift.showConversation(MyActivity.this, config);
Support.showFAQs(MyActivity.this, apiConfig);
Helpshift.showFAQs(MyActivity.this, config);
Support.showFAQSection(MyActivity.this, "11");
Support.showFAQSection(MyActivity.this, "11", apiConfig);
Helpshift.showFAQSection(MyActivity.this, "11", config);
Support.showSingleFAQ(MyActivity.this, "51");
Support.showSingleFAQ(MyActivity.this, "51", apiConfig);
Helpshift.showSingleFAQ(MyActivity.this, "51", config);
FAQ filtering by tagsCurrently not supported
Guided issue filingCurrently not supported
Embeddable fragmentsCurrently not supported

For more information on public APIs in SDK X, please refer to this document — Helpshift APIs - Helpshift SDK X for Android.

Conversation and FAQ API Configuration

Update the configuration passed in conversation and FAQ APIs as following.

Legacy SDK ApiConfigSDK X: Key in Map
ApiConfig.Builder.setShowConversationResolutionQuestionMoved to Helpshift Admin Dashboard.
Under App settings → Resolution Experience → Resolution Question toggle
ApiConfig.Builder.setEnableTypingIndicatorMoved to Helpshift Admin Dashboard.
Under App settings → Support Experience → Show Agent Typing Indicator toggle
Other configs from ApiConfig have been removedCurrently, other configs are not supported

Following deprecated configurations have been removed from the SDK:

User Management


Replace the legacy SDK login code:

HelpshiftUser user = new HelpshiftUser.Builder("unique-user-id-746501", "")
.setName("John Doe")


SDK X login :

Map<String, Object> userData = new HashMap<>();
userData.put("userId", "unique-user-id-746501");
userData.put("userEmail", """);
userData.put("userName", "John Doe");
userData.put("userAuthToken", "generated-user-authentication-token");



Replace the legacy SDK logout code:


SDK X logout :


Clear anonymous user

Replace legacy SDK clearAnonymousUser code:




User auth failure listener

Replace authentication failure listener delegate with HelpshiftEventListener in SDK X:

Remove legacy SDK Delegate:


class MyDelegate implements Delegate {

void authenticationFailed(HelpshiftUser user, AuthenticationFailureReason reason) {
// your code here


Support.setDelegate(new MyDelegate());

Use SDK X's HelpshiftEventListener for authentication failure updates:

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
// ....

public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
Log.e(TAG, reason);
// Your code here

For more information on User management, please refer to this document — Users - Helpshift SDK X for Android


We recommend that on migration to SDK X, you should log the active user in again to avoid potential inconsistencies.

Design and Customization Support

Design and Customization of SDK X has completely moved to Helpshift Dashboard.

Please remove all code related to Helpshift SDK’s design, theming, and customization. Configure them on Helpshift Dashboard instead.

For more information on Design and Customization, please refer to this document — Design - Helpshift SDK X for Android


Theming and customization is yet to be supported in SDK X and we will add it in our roadmap for 2022.

String Customization

String customization is yet to be supported. It will be moved to Helpshift Dashboard.

Remove all Helpshift SDK related string customizations done in your app as it will no longer reflect in SDK X.


Replace the following APIs from Legacy SDK to SDK X APIs for notification handling.

Core.registerDeviceToken(context, pushToken);Helpshift.registerPushToken(pushToken);
Core.handlePush(context, intent);Helpshift.handlePush(data);
Fetching notification count synchronously.
Not supported
Fetching notification count asynchronously.
Support.getNotificationCount(countHandler, failHandler);

Asynchronous requestUnreadMessageCount result is provided as an event on HelpshiftEventListener:

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
int count = (int) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT);
boolean fromCache = (boolean) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE);
if (fromCache) {
Log.d("Notification Count", "local" + count);
} else {
Log.d("Notification Count", "server" + count);

If you are using push notifications, we recommend that you register the push token again with SDK X after your app has been upgraded to avoid potential inconsistencies.

For more information on notification handling, please refer to this document — Notifications - Helpshift SDK X for Android

SDK Language


We recommend that you set the SDK language again on upgrading your app with SDK X to avoid potential inconsistencies.

For more information on internationalization, please refer to this document — Going International - Helpshift SDK X for Android


Replace legacy SDK API Support.leaveBreadCrumb("Went to Preferences Screen"); with SDK X API Helpshift.leaveBreadCrumb("Went to Preferences Screen")

Replace legacy SDK API Support.clearBreadCrumbs(); with SDK X API Helpshift.clearBreadCrumbs()

Debug logs

Legacy SDK support for Debug Logs has been replaced in SDK X with debug logs documented here

Checking active Conversation

Legacy SDK API Support.isConversationActive() is not supported in SDK X

Adding meta data for Conversations

MetaData class has been removed.

We recommened using CIF instead of meta data. You can find detailed article here

Legacy SDK leveraged metadata APIs to attach metadata to the conversation (Refer here). Replace Legacy SDK code for attaching metadata with equivalent SDK X code -

HashMap<String, String> customMetadata = new HashMap<String, String();

HashMap<String, Object> config = new HashMap<>();
config.put("customMetadata", customMetadata);

Helpshift.showConversation(MainActivity.this, config);

Adding tags to Conversations

To pass on tags as shown below in legacy SDK code:

String[] tags = new String[]{"foo", "bar"};

HashMap<String, Object> userData = new HashMap<>();
Metadata metadata = new Metadata(userData, tags);

private void showHelp () {
ApiConfig apiConfig = new ApiConfig.Builder()
Support.showFAQs(MainActivity.this, apiConfig);

Use the following SDK X API:

Map<String, Object> config = new HashMap<>();
config.put("tags", new String[]{"foo", "bar"});

Helpshift.showConversation(MainActivity.this, config);

CIF support

If you have following CIFs set in legacy SDK :

Map<String, String[]> customIssueFields = new HashMap<>();
customIssueFields.put("join_date", new String[]{"dt", "1505927361535"});
customIssueFields.put("level", new String[]{"n", "42"});
customIssueFields.put("name", new String[]{"sl", "John Doe"});
customIssueFields.put("address", new String[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
customIssueFields.put("is_pro", new String[]{"b", "true"});
customIssueFields.put("currency", new String[]{"dd", "Dollar"});


private void showHelp() {
ApiConfig apiConfig = new ApiConfig.Builder()
Support.showFAQs(MainActivity.this, apiConfig);

Use the following SDK X code to set CIFs as in above example:

Map<String, String> joiningDate = new HashMap<>();
joiningDate.put("type", "date");
joiningDate.put("value", "1505927361535");

Map<String, String> stockLevel = new HashMap<>();
stockLevel.put("type", "number");
stockLevel.put("value", "42");

Map<String, String> employeeName= new HashMap<>();
employeeName.put("type", "singleline");
employeeName.put("value", "John Doe");

Map<String, String> isPro = new HashMap<>();
isPro.put("type", "boolean");
isPro.put("value", "true");

Map<String, String> address = new HashMap<>();
address.put("type", "multiline");
address.put("value", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128");

Map<String, String> currency = new HashMap<>();
currency.put("type", "dropdown");
currency.put("value", "Dollar");

Map<String, Object> cifMap = new HashMap<>();
cifMap.put("join_date", joiningDate);
cifMap.put("level", stockLevel);
cifMap.put("name", employeeName);
cifMap.put("is_pro", isPro);
cifMap.put("address", address)
cifMap.put("currency", currency)

Map<String, Object> config = new HashMap<>();
// other configs...
config.put("customIssueFields", cifMap);

Helpshift.showFAQs(MainActivity.this, config);

Please refer to this document for further details - CIF - Helpshift SDK X Android

Helpshift Delegates

The events reported in Legacy SDKs Delegate class will now be reported in HelpshiftEventListener callback interface of SDK X. All the events are now reported in onEventOccurred method of this listener class with defined constants for expected values. You will need to update your code based on these events from the old Delegate class.

For more details on supported events, please refer to this document — Helpshift Delegates - Helpshift SDK X for Android

Following events are not supported anymore from the legacy SDK:

  • userClickOnAction

  • displayAttachmentFile

Review and Feedback

Deep links are supported in SDK X, similar to Legacy SDK — Deep Linking - Helpshift SDK X for Android


Compilation errors due to Helpshift SDK

Make sure you have removed all code related to the legacy SDK.

Check that the gradle dependency is correctly added as mentioned here

Make sure that the new/replaced API's that you are using are having the correct parameters.

Push notifications not working properly

Check that you have migrated to the new API to be used for registering push token in SDK X.

Check if you have correctly migrated to use the new API for handling push notifications i.e Helpshift.handlePush() instead of Core.handlePush()

Not getting event updates from the SDK

Check that you have registered the listener Helpshift.setHelpshiftEventListener() correctly and have migrated your event handling code from Support.setDelegate()

Contact Us

If you face any issues with respect to migrating from legacy SDK to SDK X, please contact us on