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

#1

Check migration support

Go through migration guide

#2

Update to SDK X

Migrate code/features step by step

#3

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 -

• Guided issue filing.

• Embeddable support fragments.

• FAQ filtering by tags.

• Minimum Issue description length.

• Conversation pre-fill text.

• SDK UI strings customization.

• Automated review requests.

• Switching between light and dark themes.

These features are yet to be developed, and we may add them to our 2022 roadmap. You can reach out to support@helpshift.com 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.+

Note

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 'com.android.support:appcompat-v7:28.0.0'
    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.

Note

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 {
    Helpshift.install(this,
                  "<App Id from the Helpshift Dashboard>",
                  "<Domain name from the Helpshift Dashboard>",
                  config);
} 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 InstallConfig	SDK X : Key in Map	Example Value
InstallConfig.Builder.setNotificationIcon	"notificationIcon"	R.drawable.notification_icon
InstallConfig.Builder.setLargeNotificationIcon	"notificationLargeIcon"	R.drawable.notification_large_icon
InstallConfig.Builder.setEnableInAppNotifications	"enableInAppNotification"	true/false
InstallConfig.Builder.setNotificationSound	"notificationSoundId"	R.raw.notification_sound
InstallConfig.Builder.setSupportNotificationChannelId	"notificationChannelId"	"ABC App Channel"
InstallConfig.Builder.setEnableDefaultFallbackLanguage	This config has been removed
InstallConfig.Builder.setFont	This config has been removed
InstallConfig.Builder.setScreenOrientation	"screenOrientation"	ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
InstallConfig.Builder.setEnableLogging	"enableLogging"	true/false
InstallConfig.Builder.disableErrorReporting	This config has been removed

Note

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.

Legacy SDK	SDK X
Support.showConversation(MyActivity.this); Support.showConversation(MyActivity.this, apiConfig);	Helpshift.showConversation(MyActivity.this, config);
Support.showFAQs(MyActivity.this); 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 tags	Currently not supported
Guided issue filing	Currently not supported
Embeddable fragments	Currently 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 ApiConfig	SDK X: Key in Map
ApiConfig.Builder.setEnableFullPrivacy	"fullPrivacy"
ApiConfig.Builder.setCustomIssueFields	"customIssueFields"
ApiConfig.Builder.setShowConversationResolutionQuestion	Moved to Helpshift Admin Dashboard. Under App settings → Resolution Experience → Resolution Question toggle
ApiConfig.Builder.setEnableTypingIndicator	Moved to Helpshift Admin Dashboard. Under App settings → Support Experience → Show Agent Typing Indicator toggle
Other configs from ApiConfig have been removed	Currently, other configs are not supported

Following deprecated configurations have been removed from the SDK:

• gotoConversationAfterContactUs
• requireEmail
• hideNameAndEmail
• enableTypingIndicator
• showConversationResolutionQuestion

User Management

Login

Replace the legacy SDK login code:

HelpshiftUser user = new HelpshiftUser.Builder("unique-user-id-746501", "john.doe@app.co")
                                              .setName("John Doe")
                                              .setAuthToken("generated-user-authentication-token")
                                              .build();

Core.login(user);

SDK X login :

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

Helpshift.login(userData);

Logout

Replace the legacy SDK logout code:

Core.logout()

SDK X logout :

Helpshift.logout()

Clear anonymous user

Replace legacy SDK clearAnonymousUser code:

Core.clearAnonymousUser();

SDK X API :

Helpshift.clearAnonymousUserOnLogin();

User auth failure listener

Replace authentication failure listener delegate with HelpshiftEventListener in SDK X:

Remove legacy SDK Delegate:

import com.helpshift.support.Support.Delegate
...
...

class MyDelegate implements Delegate {
    .
    .
    .
    .

    @Override
    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() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
     // ....
  }

  @Override
  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

Note

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

Note

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.

Notifications

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

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

Asynchronous requestUnreadMessageCount result is provided as an event on HelpshiftEventListener:

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT:
        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);
        }
    }
  }

Note

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

Legacy SDK	SDK X
Core.setSDKLanguage("fr");	Helpshift.setLanguage("fr");`

Note

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

Tracking

Breadcrumb

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();
customMetadata.put("usertype","paid");
customMetadata.put("level","7");
customMetadata.put("score","12345");

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()
                         .setCustomMetadata(metadata)
                         .build();
  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()
                                            .setCustomIssueFields(customIssueFields)
                                            .build();
        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

• App review request is not supported in SDK X — Review Request - Helpshift for Android

• Manual app rating request is not supported in SDK X — Manual App Rating - Helpshift for Android

• Automatic review request is not supported in SDK X — Automatic Reviews - Helpshift for Android

Deep Links

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

Troubleshooting

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 support@helpshift.com