Migration Guide

SDK X Cocos2dx 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 to migrate from the Helpshift legacy SDK Cocos2dx plugin to the SDK X Cocos2dx plugin.

Steps to migrate to SDK X Cocos2dx plugin

Migrate from legacy SDK Cocos2dx plugin to SDK X Cocos2dx plugin

#1

Check migration support

Go through migration guide

#2

Update to SDK X Cocos2dx plugin

Migrate code/features step by step

#3

Test the migration

Validate the functionality

Unsupported features

The following Legacy 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.

Supported SDK Versions

A successful migration indicates maintaining users’ data and chat history when they move from one SDK version to another. We support migration of the Helphift cocos plugin from Helpshift SDK Cocos Plugin version 4.x+ to the SDK X Cocos2dx plugin.

Note

Migration from SDK Cocos2dx plugin version < 3.x

We don’t support the migration from SDK Cocos2dx plugin version < 4.x. If you move to SDK X Cocos2dx plugin from Helpshift SDK cocos plugin version < 4.x, 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

Requirements

Cocos2d-x 3.x and above.
Supported Android OS version: 21 and above

Integration

Remove the existing Helpshift helpshift-plugin-cocos2dx content from your project.
Make sure the following files/directories are removed from your project before you integrate the SDK X Cocos2dx plugin -

Android
iOS

proj.android/app/src/com/helpshift/ or proj.android-studio/app/src/com/helpshift/
proj.android/app/libs/Helpshift.aar or proj.android-studio/app/libs/Helpshift.aar
Classes/HelpshiftCocos2dx.cpp
Classes/HelpshiftUtil.cpp
Classes/HelpshiftCocos2dxUser.cpp
Classes/HelpshiftCocos2dx.h
Classes/HelpshiftUtil.h
Classes/HelpshiftCocos2dxUser.h

Helpshift.xcframework
Classes/HelpshiftCocos2dx.mm
Classes/HelpshiftUtil.mm
Classes/HelpshiftCocos2dxUser.mm
Classes/HelpshiftCocos2dx.h
Classes/HelpshiftUtil.h
Classes/HelpshiftCocos2dxUser.h
Classes/HelpshiftCocos2dxDelegate.h
Classes/HelpshiftCocos2dxDelegate.mm

- Follow the instructions [here](/sdkx-cocos2dx/getting-started/#adding-to-project) to add Helpshift SDK X to your project.

Code Changes

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

Helpshift `install` call

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

Android
iOS

import com.helpshift.HelpshiftCocosBridge;

public class MyActivity extends Cocos2dxActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Add install configs in the config map
        Map<String, Object> config = new HashMap<>();
        //...
        // Install call
        HelpshiftCocosBridge.install(
            this,
            "<App Id from the Helpshift Dashboard>",
            "<Domain name from the Helpshift Dashboard>",
            config);
    }
}

Initialize Helpshift by including HelpshiftCocos2dx.h and calling HelpshiftCocos2dx::install in the AppDelegate::applicationDidFinishLaunching() function of your AppDelegate.cpp:

#include "HelpshiftCocos2dx.h"
...

bool AppDelegate::applicationDidFinishLaunching() {

    cocos2d::ValueMap config;
    // Add config value.

    HelpshiftCocos2dx::install( "<App Id from the Helpshift Dashboard>",
                                "<Domain name from the Helpshift Dashboard>",
                                config);
    ...

}

Refer to SDK X Cocos2dx plugin’s Getting Started guide for more information.

Helpshift install call configuration

The mapping of install config dictionary keys are -

Legacy SDK Cocos2dx plugin install config dictionary key	SDK X Cocos2dx 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.

Helpshift Conversation and FAQ APIs

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

Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
`HelpshiftCocos2dx::showConversation()`	`HelpshiftCocos2dx::showConversation(configMap)`
`HelpshiftCocos2dx::showFAQs();`	`HelpshiftCocos2dx::showFAQs(configMap)`
`HelpshiftCocos2dx::showFAQSection(sectionPublishId)`	`HelpshiftCocos2dx::ShowFAQSection(sectionId, configMap)`
`HelpshiftCocos2dx::showSingleFAQ(questionPublishId)`	`HelpshiftCocos2dx::ShowSingleFAQ(faqId, configMap)`
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 Cocos2dx plugin config dictionary key	SDK X Cocos2dx plugin config dictionary key	Notes
`enableFullPrivacy`	`fullPrivacy`	-
`enableTypingIndicator`	-	Moved to admin dashboard under App settings → Support Experience → Show Agent Typing Indicator toggle
`showConversationResolutionQuestion`	-	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.

Helpshift User Management APIs

Replace the following APIs for user login/logout -

Replace legacy SDK login code -

    HelpshiftCocosUserBuilder *userBuilder = new HelpshiftCocosUserBuilder("unique-user-id-746501", "john.doe@app.co");
    userBuilder->setName("John Doe");
    HelpshiftCocosUser user = userBuilder->build();
    HelpshiftCocos2dx::login(&user);

with SDK X login code -

cocos2d::ValueMap user;
user["userName"] = "John Doe";
user["userEmail"] = "john.doe@app.co";
user["userId"] = "unique-user-id-746501";
HelpshiftCocos2dx::login(user);

Note

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

Other user management APIs have also changed -

Action	Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
Logout	`HelpshiftCocos2dx::logout()`	`HelpshiftCocos2dx::logout()`
Clear anonymous user	`HelpshiftCocos2dx::clearAnonymousUser()`	`HelpshiftCocos2dx::clearAnonymousUserOnLogin(bool clearAnonymousUser)`

For more information on User management in the SDK X Cocos2dx plugin, refer to 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 -

HelpshiftCocos2dx::setThemes(lightThemeFileName, darkThemeFileName)
HelpshiftCocos2dx::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 Android

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

Action	Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
Register device token	`Core.registerDeviceToken(context, regid);`	`HelpshiftCocosBridge.registerPushToken ("fcm-token");`
Request unread message count	`HelpshiftCocos2dx::getNotificationCount(true/false, didReceiveNotificationCountListenerArg)`	`HelpshiftCocos2dx::requestUnreadMessageCount(shouldFetchFromServer)`

The delegate method that receives the unread message count has also changed, Legacy SDK Code -

void didReceiveNotificationCountListenerArg(int count) {
    CCLOG("HelpshiftCocos2dx::didReceiveNotificationCountListenerArg : %d.", count);
}
// Get count synchronously from cache.
HelpshiftCocos2dx::getNotificationCount(false, didReceiveNotificationCountListenerArg);
// OR
// asynchronously from the server.
HelpshiftCocos2dx::getNotificationCount(true, didReceiveNotificationCountListenerArg);

SDK X code -

void getUnreadMessageCount(Ref *pSender) {
  bool shouldFetchFromServer = true;
  HelpshiftCocos2dx::requestUnreadMessageCount(shouldFetchFromServer);
}

void updateBadgeCount(int count) {
  // Your UI Logic here
}

void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, RECEIVED_UNREAD_MESSAGE_COUNT) == 0) {
        if (eventData.find(DATA_MESSAGE_COUNT) != eventData.end()) {
          int count = eventData[DATA_MESSAGE_COUNT].asInt();
          bool countFromCache = eventData[DATA_MESSAGE_COUNT_FROM_CACHE].asBool();
          // Use the 'count' variable for further processing
          updateBadgeCount(count);
      }
    }
}

Read more about unread message count delegate here.

Handle notification

To handle notification clicks, replace legacy SDK code -

@Override
public void onMessageReceived(RemoteMessage message) {
  Map<String, String> data = message.getData();
  String origin = data.get("origin");
  if (origin != null && origin.equals("helpshift")) {
    Core.init(Support.getInstance());
    try {
        Core.install(getApplication(),
                    <API_KEY>,
                    <DOMAIN_NAME>,
                    <APP_ID>,
                    config);
      } catch (InstallException e) {
        // install credentials are incorrect
      }
    Core.handlePush(this, data);
  }
}

with SDK X code -

@Override
public void onMessageReceived(RemoteMessage message) {
  Map<String, String> data = message.getData();
  String origin = data.get("origin");
  if (origin != null && origin.equals("helpshift")) {
    HelpshiftCocosBridge.handlePushNotification(getApplicationContext(), data);
  }
}

Notification APIs iOS

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

Action	Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
Register device token	`[HelpshiftCore registerDeviceToken:deviceToken];`	`[Helpshift registerDeviceToken:deviceToken];`
Request unread message count	`HelpshiftCocos2dx::getNotificationCount(shouldFetchFromServer, didReceiveNotificationCountListenerArg)`	`HelpshiftCocos2dx::requestUnreadMessageCount(shouldFetchFromServer)`

The delegate method that receives the unread message count has also changed. Replace legacy SDK code

void didReceiveNotificationCountListenerArg(int count) {
    CCLOG("HelpshiftCocos2dx::didReceiveNotificationCountListenerArg : %d.", count);
}
// Get count synchronously from cache.
HelpshiftCocos2dx::getNotificationCount(false, didReceiveNotificationCountListenerArg);
// OR
// asynchronously from the server.
HelpshiftCocos2dx::getNotificationCount(true, didReceiveNotificationCountListenerArg);

SDK X code -

void getUnreadMessageCount(Ref *pSender) {
  bool shouldFetchFromServer = true;
  HelpshiftCocos2dx::requestUnreadMessageCount(shouldFetchFromServer);
}

void updateBadgeCount(int count) {
  // Your UI Logic here
}

void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, RECEIVED_UNREAD_MESSAGE_COUNT) == 0) {
        if (eventData.find(DATA_MESSAGE_COUNT) != eventData.end()) {
          int count = eventData[DATA_MESSAGE_COUNT].asInt();
          bool countFromCache = eventData[DATA_MESSAGE_COUNT_FROM_CACHE].asBool();
          // Use the 'count' variable for further processing
          updateBadgeCount(count);
      }
    }
}

Read more about unread message count delegate here.

Handle notification

To handle notification clicks, replace legacy SDK code -

#import <HelpshiftX/Helpshift.h>
...
- (void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    if([[userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
        [HelpshiftCore handleRemoteNotification:userInfo
                                isAppLaunch:false
                              withController:self.window.rootViewController];
    }
}

SDK X code -

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
         withCompletionHandler:(void (^)(void))completionHandler {
    if([[response.notification.request.content.userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
        [Helpshift handleNotificationWithUserInfoDictionary:response.notification.request.content.userInfo
                                                isAppLaunch:YES
                                             withController:self.window.rootViewController];
    } else {
        // Handling for non-helpshift push notifications received when app is in background or killed
    }
    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, refer to Notifications guide. For more information on delegates in SDK X, refer to Delegates guide.

Internationalization

The API to set SDK language has changed -

Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
`HelpshiftCocos2dx::setLanguage("zh_CN");`	`HelpshiftCocos2dx::setLanguage("zh-CN");`

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.

Tracking

Replace the following APIs from the legacy SDK Cocos2dx plugin -

Metadata and Tags

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 -

ValueMap config;
ValueMap meta;
meta["usertype"] = Value("paid");
meta["level"] = Value("7");
meta["score"] = Value("12345");

ValueVector tags;
tags.push_back(Value("feedback"));
tags.push_back(Value("paid user"));

meta[HS_TAGS_KEY] = Value(tags);
config[HS_META_DATA_KEY] = Value(meta);

HelpshiftCocos2dx::showFAQs(config);

with equivalent SDK X code -

ValueMap config;
ValueMap meta;
meta["usertype"] = Value("paid");
meta["level"] = Value("7");
meta["score"] = Value("12345");

ValueVector tags;
tags.push_back(Value("foo"));
tags.push_back(Value("bar"));

config["tags"] = tags;
config["customMetadata"] = Value(meta);

HelpshiftCocos2dx::showFAQs(config);

Custom Issue Fields

Replace legacy SDK code -

ValueMap customIssueFields;
ValueVector singleLineData;
singleLineData.push_back(Value("sl"));
singleLineData.push_back(Value("John Doe"));
customIssueFields["name"] = Value(singleLineData);

ValueVector multiLineData;
multiLineData.push_back(Value("ml"));
multiLineData.push_back(Value("This is user's long bio"));
customIssueFields["address"] = Value(multiLineData);

ValueVector integerData;
integerData.push_back(Value("n"));
integerData.push_back(Value("42"));
customIssueFields["level"] = Value(integerData);

ValueVector booleanData;
booleanData.push_back(Value("b"));
booleanData.push_back(Value("true"));
customIssueFields["is_pro"] = Value(booleanData);

ValueVector dropdownData;
dropdownData.push_back(Value("dd"));
dropdownData.push_back(Value("Dollar"));
customIssueFields["currency"] = Value(dropdownData);

ValueVector dateData;
dateData.push_back(Value("dt"));
dateData.push_back(Value("1505927361535"));
customIssueFields["join_date"] = Value(dateData);

ValueMap config;
config[HS_CUSTOM_ISSUE_FIELDS] = Value(customIssueFields);

HelpshiftCocos2dx::showFAQs(config)

with SDK X code -

cocos2d::ValueMap createValueMap(const std::string& type, Value value) {
    cocos2d::ValueMap valueMap;
    valueMap["type"] = cocos2d::Value(type);
    valueMap["value"] = cocos2d::Value(std::move(value));
    return valueMap;
}

cocos2d::ValueMap getCifs() {
    cocos2d::ValueMap cifMap;
    cifMap["joining_date"] = createValueMap("date", Value("1684747527945"));
    cifMap["stock_level"] = createValueMap("number", Value("1500"));
    cifMap["employee_name"] = createValueMap("singleline", Value("Captain Marvel"));
    cifMap["is_pro"] = createValueMap("boolean", Value("true"));
    cifMap["salary_currency"] = createValueMap("dropdown", Value("Dollars"));
    cifMap["essay"] = createValueMap("multiline", Value("Education holds the key to unlocking our potential and shaping a better future. It equips individuals with knowledge, skills, and critical thinking abilities necessary for personal growth and societal progress. Through education, we gain a broader understanding of the world and develop empathy and compassion. It empowers us to challenge existing norms, break barriers, and create meaningful change. Education is not merely confined to classrooms; it is a lifelong journey of exploration and self-discovery. Let us embrace the transformative power of education and strive for a brighter tomorrow."));

    return cifMap;
}


cocos2d::ValueMap getConfig() {
  cocos2d::ValueMap configMap;

  ValueVector tags;
  tags.push_back(Value("foo"));
  tags.push_back(Value("bar"));

  configMap["tags"] = tags;
  configMap["cifs"] = getCifs();

  return configMap;
}

void HelloWorld::showConversation(Ref *pSender) {
    cocos2d::ValueMap chatConfig = getConfig();
    HelpshiftCocos2dx::showConversation(chatConfig);
}

Breadcrumbs

The APIs for breadcrumbs have not changed -

Action	Legacy SDK Cocos2dx plugin API	SDK X Cocos2dx plugin API
Leave breadcrumbs	`HelpshiftCocos2dx::leaveBreadCrumb(breadCrumb)`	`HelpshiftCocos2dx::leaveBreadCrumb(breadcrumb)`
Clear breadcrumbs	`HelpshiftCocos2dx::clearBreadCrumbs()`	`HelpshiftCocos2dx::clearBreadCrumbs()`

Debug Logs

The API signature for adding debug logs hasn’t changed. We have the same class named as HelpshiftLog in SDK X Cocos2dx 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 Cocos2dx plugin API	SDK X Cocos2dx plugin API
`HelpshiftCocos2dx::registerDelegates()`	`HelpshiftCocos2dx::setHelpshiftEventsListener(handleHelpshiftEvent, handleAuthFailureEvent)`

Each SDK event had a separate method in the legacy SDK Cocos2dx plugin. In SDK X Cocos2dx plugin, all events are received in the delegate’s handleHelpshiftEvent(eventName,eventData) method. For a list of events, refer to this guide.

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

userClickOnAction(serializedJSONUserActionData)
displayAttachmentFile(path)
didCheckIfConversationActive(isActive)

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:

Troubleshooting

Compilation errors after upgrading to SDK X Cocos2dx plugin

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

Contact Us

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

Migration Guide

Steps to migrate to SDK X Cocos2dx plugin​

#1

#2

#3

Unsupported features​

Supported SDK Versions​

Update Helpshift dependencies​

Requirements​

Integration​

Code Changes​

Helpshift install call​

Helpshift install call configuration​

Helpshift Conversation and FAQ APIs​

Conversation and FAQ API Configuration​

Helpshift User Management APIs​

Login​

Design and Theming​

String Customization​

Notification APIs Android​

Handle notification​

Notification APIs iOS​

Handle notification​

Internationalization​

Tracking​

Metadata and Tags​

Custom Issue Fields​

Breadcrumbs​

Debug Logs​

Helpshift Delegates​

Reviews & Feedback​

Troubleshooting​

Contact Us​

Steps to migrate to SDK X Cocos2dx plugin

Unsupported features

Supported SDK Versions

Update Helpshift dependencies

Requirements

Integration

Code Changes

Helpshift `install` call

Helpshift install call configuration

Helpshift Conversation and FAQ APIs

Conversation and FAQ API Configuration

Helpshift User Management APIs

Login

Design and Theming

String Customization

Notification APIs Android

Handle notification

Notification APIs iOS

Handle notification

Internationalization

Tracking

Metadata and Tags

Custom Issue Fields

Breadcrumbs

Debug Logs

Helpshift Delegates

Reviews & Feedback

Troubleshooting

Contact Us