Migration Guide

Steps to migrate to SDK X

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.+

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.

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.

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.

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.

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

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

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.

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);
        }
    }
  }

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

SDK Language

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