Migration Guide

SDK X Xamarin plugin 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.

This migration guide will walk you through the steps you need to take in order to migrate from Helpshift legacy Xamarin plugin to SDK X Xamarin plugin.

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

The following Legay SDK features are unavailable in SDK X. If your workflow requires one or more of these features, please reach out to our support team for the latest information.

Guided issue filing (iOS) (Android).
FAQ filtering by tags (iOS) (Android).
Minimum Issue description length (iOS) (Android).
SDK UI strings customization (iOS) (Android).
Automated review requests (iOS) (Android).
Switching between light and dark themes (iOS) (Android).

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 Xamarin plugin from version 3.0.0+ to SDK X Xamarin 10.2.0+

Note

Migration from legacy SDK Xamarin plugin version < 3.0.0

We don’t support the migration from legacy SDK Xamarin plugin version < 3.0.0. If you move to SDK X from version < 3.0.0, 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.

Update Helpshift dependencies

Integration

Remove the existing Helpshift DLLs from your Xamarin projects. The DLLs are -

HelpshiftApi.dll in the common Xamarin project
HelpshiftApi.dll in the Xamarin Android project
HelpshiftApi.dll in the Xamarin iOS project
Helpshift.IOS.dll in the Xamarin iOS project

After removing the DLLs, follow the instructions here to add Helpshift SDK X to your project.

Code Changes

If you try to build your Xamarin project after updating the Helpshift dependency, you will get compilation errors. This is because some API method names and signatures have changed in SDK X.

Helpshift `Install` call

Remove the existing Helpshift install call and replace it with the following -

iOS
Android

using HelpshiftApi;

namespace App
{
    public class AppDelegate : UIApplicationDelegate
    {
        public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
        {
            Dictionary<string, object> installConfig = new Dictionary<string, object>();
            // Add any install config parameters to installConfig
            Helpshift.Install("YOUR_APP_ID", "YOUR_DOMAIN_NAME", installConfig);
        }
    }
}

using HelpshiftApi;

namespace App
{
    [Application]
    public class MyApplication : Application
    {
        override public void OnCreate()
        {
            base.OnCreate();
            Dictionary<string, object> installConfig = new Dictionary<string, object>();
            // Add any install config parameters to installConfig
            Helpshift.Install("YOUR_APP_ID", "YOUR_DOMAIN_NAME", installConfig);
        }
    }
}

Please refer to Getting Started guide for more information.

Helpshift install call configuration

The mapping of install config dictionary keys are -

Legacy SDK Xamarin plugin install config dictionary key	SDK X Xamarin plugin install config dictionary key
`"enableLogging"`	`"enableLogging"`
`"enableInAppNotification"`	`"enableInAppNotification"`

All other deprecated configurations have been removed and are not supported anymore. For more information about install configurations, check the configuration guide.

Conversation and FAQ APIs

The API signatures have changed. Update existing API calls with new ones as follows -

Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
`ShowConversation(object, HelpshiftAPIConfig)`	`ShowConversation(object, Dictionary)`
`ShowFAQs(object, HelpshiftAPIConfig)`	`ShowFAQs(object, Dictionary)`
`ShowFAQSection(string, object, HelpshiftAPIConfig)`	`ShowFAQSection(string, object, Dictionary)`
`showSingleFAQ(string, object, HelpshiftAPIConfig)`	`ShowSingleFAQ(string, object, Dictionary)`
FAQ Filtering by tags	Currently not supported
Guided issue filing	Currently not supported

For more information about Conversation and FAQs APIs, check the Helpshift APIs guide.

Conversation and FAQ API Configuration

The mapping of config dictionary keys are -

Legacy SDK Xamarin plugin builder API/config dictionary key	SDK X Xamarin plugin config dictionary key	Notes
`HelpshiftAPIConfig.Builder.SetCustomissueFields()`	`cifs`	-
`HelpshiftAPIConfig.Builder.SetEnableFullPrivacy(bool)`	`fullPrivacy`	-
`presentFullScreenOniPad`	`presentFullScreenOniPad`	-
`HelpshiftAPIConfig.Builder.SetEnableTypingIndicator(bool)`	-	Moved to admin dashboard under App settings → Support Experience → Show Agent Typing Indicator toggle
`HelpshiftAPIConfig.Builder.SetShowConversationResolutionQuestion(bool)`	-	Moved to admin dashboard under App settings → Resolution Experience → Resolution Question toggle

All other configurations have been deprecated and are no longer supported. For more information about API configurations, check the configuration guide.

User Management APIs

Replace the legacy SDK login code:

HelpshiftUser user = new HelpshiftUser.Builder("user-id", "user-email")
                                      .SetName("user-name")
                                      .SetAuthToken("auth-token")
                                      .Build();
HelpshiftCore.Login(user);

SDK X login :

Dictionary<string, string> data = new Dictionary<string, string>();
data["userId"] = "user-id";
data["userEmail"] = "user-email";
data["userName"] = "user-name";
data["userAuthToken"] = "auth-token";
Helpshift.Login(data);

Note

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

Other user management APIs have also changed -

Action	Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
Logout	`HelpshiftCore.Logout()`	`Helpshift.Logout()`
Clear anonymous user	`HelpshiftCore.ClearAnonymousUser()`	`Helpshift.ClearAnonymousUser(bool)`

For more information about User management, check the Users guide.

Design and Theming

SDK’s design and theming have been completely moved to the admin dashboard in SDK X. Please remove all calls to theming APIs and all theming-related files from your project. Removed APIs -

SetThemes(lightThemeFileName, darkThemeFileName)
SetTheme(themeName)

Theming can be configured from the admin dashboard. You can find more details in the SDK X theming guide.

String Customization

String customization is yet to be supported. It will move to Helpshift Dashboard. Remove all Helpshift SDK related string customizations done in your project as they will no longer reflect in SDK X.

Notification APIs

The API signatures have changed. Update existing API calls with new ones as mentioned -

Action	Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
Register push token	`HelpshiftCore.RegisterDeviceToken(string)`	`Helpshift.RegisterPushToken(string)`
Request unread message count	`HelpshiftSupport.RequestUnreadMessagesCount(bool)`	`Helpshift.RequestUnreadMessageCount(bool)`

The delegate method that receives the unread message count has also changed from -

// Define Helpshift support delegate
public class  HSDelegate : ISupportDelegate 
{
    public void DidReceiveUnreadMessagesCount(int count)
    {
      // Legacy SDK unread message count handling here
    }
}

// Register delegate with Helpshift
HSDelegate delegateObject = new HSDelegate();
HelpshiftSupport.SetDelegate(delegateObject);

// Request unread message count
HelpshiftSupport.RequestUnreadMessagesCount(true);

to -

// Define Helpshift events listener
public class  HSDelegate : IHelpshiftEventsListener 
{
  public void OnEventOccurred(string eventName, IDictionary<string, object> data)
  {
    switch(eventName)
    {
      case HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT:
        // SDK X unread message count handling here
        break;
    }
  }
}

// Register events listener with Helpshift
Helpshift.SetHelpshiftEventsListener(new HSDelegate());

// Request unread message count
Helpshift.RequestUnreadMessageCount(true);

Handle push notification clicks

To handle notification clicks, replace legacy SDK code -

public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
{
  //  Check if the app is launched through a push notification
  if (launchOptions != null && launchOptions.Keys != null && launchOptions.ContainsKey(new NSString("UIApplicationLaunchOptionsRemoteNotificationKey")))
  {
    NSDictionary userInfo = launchOptions.ObjectForKey(new NSString("UIApplicationLaunchOptionsRemoteNotificationKey")) as NSDictionary;

    //  Check if the notification belongs to Helpshift
    if (userInfo.ObjectForKey((NSString)"origin").IsEqual((NSString)"helpshift"))
    {
      var vc = // Get root ViewController of your app
      HelpshiftCore.HandlePushNotification(userInfo, true, vc);
    }
  }
}

public override void DidReceiveRemoteNotification(UIApplication application, NSDictionary userInfo, System.Action<UIBackgroundFetchResult> completionHandler)
{
  NSObject originVal = userInfo.ObjectForKey((NSString)"origin");
  // Check if the notification belongs to Helpshift
  // Check if it was not handled from FinishedLaunching
  if (originVal != null && originVal.IsEqual((NSString)"helpshift") && !pushHandledFromFinishedLaunching)
  {
    var vc = // Get root ViewController of your app
    // Call the push handler API
    HelpshiftCore.HandlePushNotification(userInfo, false, vc);
  }

  // Reset the boolean flag (This flag can be a member of the AppDelegate class)
  pushHandledFromFinishedLaunching = false;
}

with SDK X code -

public void WillPresentNotification(UNUserNotificationCenter center, UNNotification notification, Action<UNNotificationPresentationOptions> completionHandler)
{
    var userInfo = notification.Request.Content.UserInfo;
    if (userInfo["origin"] != null && userInfo["origin"].IsEqual((NSString)"helpshift"))
    {
        Helpshift.HandlePush(userInfo, false);
        completionHandler(UNNotificationPresentationOptions.None);
    }
    else
    {
      // Handle non-helpshift notifications
    }
}

public void DidReceiveNotificationResponse(UNUserNotificationCenter center, UNNotificationResponse response, Action completionHandler)
{
    var userInfo = response.Notification.Request.Content.UserInfo;
    if (userInfo["origin"] != null && userInfo["origin"].IsEqual((NSString)"helpshift"))
    {
        Helpshift.HandlePush(userInfo, true);
    }
    else
    {
      // Handle non-helpshift notifications
    }
    completionHandler();
}

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 APIs in SDK X Xamarin, refer to Notifications guides for iOS and Android. For more information on delegates in SDK X, refer to Delegates guide.

SDK Language

The API to set SDK language has changed -

Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
`SetSDKLanguage(string)`	`SetLanguage(string)`

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 in SDK X and a list of supported languages, refer Internationalization guide.

Metadata

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 -

Dictionary<string, string> customMetadataDictionary = new Dictionary<string, string>();
customMetadataDictionary.Add("Level", "9");
customMetadataDictionary.Add("Spend", "46.55 USD");
customMetadataDictionary.Add("Device Timestamp", DateTime.UtcNow.ToLongTimeString());

Dictionary<string, object> configDictionary = new Dictionary<string, object>();

configDictionary.Add("customMetadata", customMetadataDictionary)
Helpshift.ShowFAQs(ui, configDictionary);

Custom Issue Fields

Replace legacy SDK code -

Dictionary<string, string[]> customIssueFields = new Dictionary<string, string[]>();

// The format for calling Add is customIssueFields.Add(<key>, new string[]{<datatype>, <value>});
customIssueFields.Add("join_date", new string[]{"dt", "1505927361535"});
customIssueFields.Add("level", new string[]{"n", "42"});
customIssueFields.Add("name", new string[]{"sl", "John Doe"});
customIssueFields.Add("address", new string[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
customIssueFields.Add("is_pro", new string[]{"b", "true"});
customIssueFields.Add("currency", new string[]{"dd", "Dollar"});

HelpshiftAPIConfig apiConfig = new HelpshiftAPIConfig.Builder()
                                                     .SetCustomIssueFields(customIssueFields)
                                                     .Build();
HelpshiftSupport.ShowFAQs(ui, apiConfig);

with SDK X code -

Dictionary<string, object> cifDictionary = new Dictionary<string, object>();

Dictionary<string, object> joiningDate = new Dictionary<string, object>();
joiningDate.Add("type", "date");
joiningDate.Add("value", DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());

Dictionary<string, string> stockLevel = new Dictionary<string, string>();
stockLevel.Add("type", "number");
stockLevel.Add("value", "42");

Dictionary<string, string> employeeName = new Dictionary<string, string>();
employeeName.Add("type", "singleline");
employeeName.Add("value", "John Doe");

Dictionary<string, string> address = new Dictionary<string, string>();
address.Add("type", "multiline");
address.Add("value", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128");

Dictionary<string, string> isPro = new Dictionary<string, string>();
isPro.Add("type", "boolean");
isPro.Add("value", "true");

Dictionary<string, string> currency = new Dictionary<string, string>();
isPro.Add("type", "dropdown");
isPro.Add("value", "Dollar");

cifDictionary.Add("join_date", joiningDate);
cifDictionary.Add("level", stockLevel);
cifDictionary.Add("name", employeeName);
cifDictionary.Add("address", address);
cifDictionary.Add("is_pro", isPro);
cifDictionary.Add("currency", currency);

Dictionary<string, bbject> config = new Dictionary<string, object>();
config.Add("cifs", cifDictionary);
Helpshift.ShowFAQs(ui, config);

For more information on Metadata, Tags and Custom Issue Fields in SDK X, refer Tracking guide.

The APIs for breadcrumbs have changed -

Action	Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
Leave breadcrumbs	`HelpshiftSupport.LeaveBreadCrumb(string)`	`Helpshift.LeaveBreadCrumb(string)`
Clear breadcrumbs	`HelpshiftSupport.ClearBreadCrumbs()`	`Helpshift.ClearBreadCrumbs()`

The API signature for adding debug log hasn’t changed. We have the same class named as HelpshiftLogger in SDK X Xamarin plugin for adding logs. You can use its methods for adding logs.

You can find more details in the Tracking guide.

Helpshift Delegates

The API to register Helpshift delegate has been changed -

Legacy SDK Xamarin plugin API	SDK X Xamarin plugin API
`HelpshiftSupport.SetDelegate(ISupportDelegate)`	`Helpshift.SetHelpshiftEventsListener(IHelpshiftEventsListener)`

Each SDK event had a separate method in the legacy SDK Xamarin plugin. In SDK X Xamarin plugin, all events are received in the delegate’s OnEventOccurred(string,IDictionary<string, object>) method. For a list of events, refer to this guide.

Legacy SDK Xamarin plugin methods that are unsupported in SDK X Xamarin plugin and don't have a corresponding event are -

UserDidClickOnActionWithTypeAndData(HelpshiftActionType, string)
HandleTapOnAttachmentFile(string)
DidCheckIfConversationActive(bool)

You can find more details about delegates in the Delegates guide.

Reviews & Feedback

App Review by an agent is supported in SDK X. You can learn more about this feature here

Following have been deprecated in SDK X:

Manual App Rating request. Refer Android / iOS
Automatic Reviews request. Refer Android / iOS

Deep linking

Deep links are supported in SDK X, similar to Legacy SDK. Refer to deep links guide for more information.

Troubleshooting

Compilation errors after upgrading to SDK X Xamarin plugin

For supported APIs or configurations, make sure you have replaced all legacy SDK Xamarin plugin code with the corresponding SDK X Xamarin plugin code as mentioned in this guide.
For unsupported APIs or configurations, make sure you have removed all legacy SDK Xamarin plugin code as mentioned in this guide.

Contact Us

If you face any issues regarding the migration from the legacy SDK Xamarin plugin to the SDK X Xamarin plugin, please contact us at support@helpshift.com.

Migration Guide

Steps to migrate to SDK X​

#1

#2

#3

Unsupported features​

Supported SDK versions​

Update Helpshift dependencies​

Integration​

Code Changes​

Helpshift Install call​

Helpshift install call configuration​

Conversation and FAQ APIs​

Conversation and FAQ API Configuration​

User Management APIs​

Design and Theming​

String Customization​

Notification APIs​

Handle push notification clicks​

SDK Language​

Metadata​

Tags​

Custom Issue Fields​

Breadcrumb & Debug Logs​

Helpshift Delegates​

Reviews & Feedback​

Deep linking​

Troubleshooting​

Contact Us​

Steps to migrate to SDK X

Unsupported features

Supported SDK versions

Update Helpshift dependencies

Integration

Code Changes

Helpshift `Install` call

Helpshift install call configuration

Conversation and FAQ APIs

Conversation and FAQ API Configuration

User Management APIs

Design and Theming

String Customization

Notification APIs

Handle push notification clicks

SDK Language

Metadata

Tags

Custom Issue Fields

Breadcrumb & Debug Logs

Helpshift Delegates

Reviews & Feedback

Deep linking

Troubleshooting

Contact Us