Skip to main content

SDK Configuration

Important
Helpshift’s Legacy SDKs (SDK Version <=7.x.x) reached their end of life on 31 Dec 2022, and end of support on 31 March 2023. Please upgrade to the Latest SDKif you haven't already.

SDK Configuration

Helpshift provides several config options which can be used to customize behaviour of the SDK. These options are boolean flags which can be passed with the Helpshift APIs such as showConversation, showFAQs etc.

enableAutomaticThemeSwitching​

Upon setting this option to YES, Helpshift SDK will switch between default light and dark themes based on the OS Appearance setting.

OptionHS_ENABLE_AUTOMATIC_THEME_SWITCHING
Values"yes" / "no"
Default"no"
Min SDKv5.2.0
Supported byinstall(apiKey, domainName, appID, config)

Example:

#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)

ValueMap config;
config[HS_ENABLE_AUTOMATIC_THEME_SWITCHING] = Value("yes");

HelpshiftCocos2dx::install("apiKey",
                           "domainName",
                           "appId",
                           config);
#endif
Note
  1. This configuration is only applicable to iOS 13 and above.
  2. Light and Dark Appearance switching works only if your app is built with Xcode 11 or above
  3. If you use setTheme or setLightTheme:DarkTheme API, this config takes no effect.

enableInAppNotification​

FlagenableInAppNotification
Values"yes"/ "no"
Default"yes"

For example:

ValueMap config;
config[HS_ENABLE_IN_APP_NOTIFICATION] = "yes";
HelpshiftCocos2dx::showConversation(config);

If you want to disable the in-app notifications, please set this variable to "no" in the config dictionary passed to the install.

enableContactUs​

FlagenableContactUs
ValuesHS_ENABLE_CONTACT_US_ALWAYS/HS_ENABLE_CONTACT_US_NEVER/HS_ENABLE_CONTACT_US_AFTER_VIEWING_FAQS
DefaultHS_ENABLE_CONTACT_US_ALWAYS

The enableContactUs flag controls the visibility of Contact Us button -

HS_ENABLE_CONTACT_US_ALWAYSshow in the navigation bar, search, and after marking an FAQ unhelpful. "yes" for SDK versions below 4.5.0
HS_ENABLE_CONTACT_US_AFTER_VIEWING_FAQSshow only while searching, on FAQ screen and after marking an FAQ unhelpful.
HS_ENABLE_CONTACT_US_NEVERdo not show "Contact Us" button anywhere in the SDK. "no" for SDK versions below 4.5.0
HS_ENABLE_CONTACT_US_AFTER_MARKING_ANSWER_UNHELPFULdo not show "Contact Us" button until the user specifically marks an FAQ as unhelpful.

To override the default value you can pass the arguments in the options dictionary.

For example:

ValueMap config;
config[HS_ENABLE_CONTACT_US] = Value(HS_ENABLE_CONTACT_US_NEVER);
HelpshiftCocos2dx::showFAQs(config);

This flag has no effect for the showConversation API call, since there is no Contact Us button in the conversation screen.

gotoConversationAfterContactUs​

FlaggotoConversationAfterContactUs
Values"yes"/ "no"
Default"no"

The gotoConversationAfterContactUs flag will determine whether the user lands up in the conversation screen after starting a new conversation via "Contact Us". This only makes sense if the enableContactUs flag takes on the default value.

For example:

ValueMap config;
config[HS_GOTO_CONVERSATION_AFTER_CONTACT_US] = Value("yes");

Helpshiftcocos2dx::showFAQs(config)
Note

For showFAQs, showFAQSection and showSingleFAQ, setting gotoConversationAfterContactUs makes sense only if enableContactUs is yes.

Note

This API is now deprecated with Cocos2d-x SDK v4.0.0. Read more about the new conversational experience here.

presentFullScreenOniPad​

FlagpresentFullScreenOniPad
Values"yes" / "no"
Default"no"

The presentFullScreenOniPad flag will determine whether to present support views in UIModalPresentationFullScreen or UIModalPresentationFormSheet modal presentation style in iPad.

The default value is "no", which means support views will be presented as UIModalPresentationFormSheet by default. When the value is set to "yes", support views will be presented in UIModalPresentationFullScreen.

For example:

ValueMap config;
config[HS_PRESENT_FULL_SCREEN_ON_IPAD] = "yes";
HelpshiftCocos2dx::showConversation(config);

This flag only takes effect on iPad.

requireEmail​

FlagrequireEmail
Values"yes" / "no"
Default"no"

The requireEmail flag will determine whether email is required or optional for starting a new conversation.

When the flag is set to yes customer's email will be required. If set to no email will be optional.

For example:

ValueMap config;
config[HS_REQUIRE_EMAIL] = Value("yes");
HelpshiftCocos2dx::showFAQs(config);

If "New Issue Forwarding" is ON or if "Allow anonymous issues" is ON in the agent dashboard, then this flag will be ignored.

Note

Once requireEmail flag is set, the SDK will use that value for all new conversations until it is changed again.

Note

This API is now deprecated with Cocos2d-x SDK v4.0.0. Read more about the new conversational experience here.

hideNameAndEmail​

FlaghideNameAndEmail
Values"yes" / "no"
Default"no"

The hideNameAndEmail flag will hide the name and email fields when the user starts a new conversation.

When the flag is set to yes the name and email fields will be hidden. If set to no the default behaviour will resume.

If "New Issue Forwarding" is ON then this flag will be ignored when name and email are not available to the SDK. You can use the setNameAndEmail API, to supply the SDK with name and email in this case.

If "Allow anonymous issues" is ON, under app settings in the agent dashboard, then this flag will be ignored.

Also, if the requireEmail flag is set to no and email is not available to the SDK, then hideNameAndEmail flag will be ignored.

For example:

ValueMap config;
config[HS_HIDE_NAME_AND_EMAIL] = Value("yes");
HelpshiftCocos2dx::showFAQs(config);
Note

Once hideNameAndEmail flag is set, the SDK will use that value for all new conversations until it is changed again.

Note

This API is now deprecated with Cocos2d-x SDK v4.0.0. Read more about the new conversational experience here.

conversationPrefillText​

FlagconversationPrefillText
ValuesNon-empty string

The conversationPrefillText API option will prefill a new conversation description, with the supplied string. This is useful where you might want your users to send you diagnostic information in the conversation description, for example if the app hits an exception, etc.

For example:

ValueMap config;
config[HS_CONVERSATION_PREFILL_TEXT] = Value("This is prefilled");
HelpshiftCocos2dx::showConversation(config);
Note

The conversationPrefillText option takes effect only for the showConversation API.

enableFullPrivacy​

FlagenableFullPrivacy
Values"yes" / "no"
Default"no"

In scenarios where the user attaches objectionable content in the screenshots, it becomes a huge COPPA concern. The enableFullPrivacy option will help solve this problem.

If enableFullPrivacy option is set to "yes", HS SDK does the following:

  1. Disables user-initiated screenshots - players cannot send images without being requested by an Agent.
  2. Does not collect any of the following personal information:
    • Mobile country code, mobile network code and carrier name.
    • Country code and country.
    • Custom meta-data that is labeled "private-data".

To send personally identifiable information through custom meta-data, the information must be added inside a dictionary with a "private-data" key. If this option is set to YES, this data will be removed when the user starts a new conversation.

For example:

ValueMap config;
config[HS_ENABLE_FULL_PRIVACY] = Value("yes");
HelpshiftCocos2dx::showConversation(config);

Best Practices​

In your registration process, ask your user for his/her age. If the user's age is 13 or younger, set enableFullPrivacy to "yes". This way, you comply with COPPA for your children users, but collect valuable user and device data for your other users.

Note
  1. Once enableFullPrivacy flag is set, the SDK will use that value for all further sessions until it is changed again.
  2. For SDK versions 1.6.0 and below, if the enableFullPrivacy flag is set, the email collection requirement is always set to optional. If requiredEmail is true, enableFullPrivacy will override this configuration and set the email requirement as optional. For hiding name and email for all users, developers enable a Dashboard configuration named "Allow anonymous issues".
  3. For SDK versions 1.7.0 and above, if the enableFullPrivacy flag is set, email and name will not be collected and the fields will be hidden. enableFullPrivacy will override all other flags pertaining to name and email fields. This will allow developers to hide name and email for a specific set of users exposed to the enableFullPrivacy flag.

showSearchOnNewConversation​

FlagshowSearchOnNewConversation
Values"yes" / "no"
Default"no"

If showSearchOnNewConversation flag is set to yes, the user will be taken to a view which shows the search results relevant to the conversation text that he has entered upon clicking the 'Send' button. This is to avoid issues which are already answered in the FAQs. The user will still be able to start a new conversation with the same text. He can also go through one of the FAQs and find a solution to his query, and exit the session without submitting an issue.

Default value is no, ie., this feature will not be enabled unless you explicitly pass yes for this flag.

For example:

ValueMap config;
config[HS_SHOW_SEARCH_ON_NEW_CONVERSATION] = Value("yes");
HelpshiftCocos2dx::showConversation(config);
Note

The showSearchOnNewConversation option takes effect only for the showConversation API.

Note

This API is now deprecated with Cocos2d-x SDK v4.0.0. Read more about the new conversational experience here.

showConversationResolutionQuestion​

The Helpshift iOS SDK will show the conversation resolution question to the user to confirm if the conversation was resolved. After the Issue has been resolved, the user will be taken back to the "Start a new conversation" state.

For Cosos2d-x v4.0+​

This SDK configuration is deprecated with v4.0+ and default value will be treated as False.

If you want to use this feature, you can turn the feature on and off ("Resolution Question") from the In-App Configuration page.(Settings > App settings)

For Older Cosos2d-x versions v1.9.0 and below, please read the following:​

FlagshowConversationResolutionQuestion
Values"yes"/"no"
DefaultBefore 5.3.0: "yes" 5.3.0 onwards: "no"

By default the Helpshift SDK will show the conversation resolution question to the user, to confirm if the conversation was resolved. On resolving the conversation from the admin dashboard will now take the user directly to the "Start a new conversation" state. If you want to disable the conversation resolution question, set showConversationResolutionQuestion to no.

Default value is yes, ie., this feature will not be disabled unless you explicitly pass false for this flag.

For example:

ValueMap config;
config[HS_SHOW_CONVERSATION_RESOLUTION_QUESTION] = Value("no");
HelpshiftCocos2dx::showConversation(config);

enableDefaultFallbackLanguage​

FlagenableDefaultFallbackLanguage
values"yes"/"no"
defaultBefore 5.3.0: "yes" After 5.3.0: "no"

You can enable or disable the SDK default fallback language when showing FAQs using this flag. When set to false, the Helpshift SDK will not fallback to the default language that is English, when showing FAQs. This flag is to be passed only in the config for the HelpshiftCocos2dx::install call.

For example:

ValueMap config;
config[HS_ENABLE_DEFAULT_FALL_BACK_LANGUAGE] = Value("yes");

#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
HelpshiftCocos2dx::install("apikey",
                           "domain.helpshift.com",
                           "appId",
                           config);
#endif
Note

This configuration does not apply to the QuickSearch Bot suggested FAQs.

disableEntryExitAnimations​

This option disables the iOS view transition animations when launching or closing a Helpshift Support session.

OptiondisableEntryExitAnimations
Values"yes" / "no"
Default"no"

If you want to disable the in-app notifications, please set this variable to "yes" in the config dictionary passed to the install.

customContactUsFlows​

This configuration allows you to override the Contact Us buttons inside the Helpshift SDK and show Guided Issue Filing when a user taps on the Contact Us buttons.

OptioncustomContactUsFlows
ValueNSArray of flows. Flows can be created by using the Guided Issue Filing APIs
DefaultThere is no default value for this configuration.

For example:

ValueMap config;
config[HS_DISABLE_ENTRY_EXIT_ANIMATIONS] = "yes";
HelpshiftCocos2dx::showConversation(config);

This configuration allows you to override the Contact Us buttons inside the Helpshift SDK and show Guided Issue Filing when a user taps on the Contact Us buttons.

For example:

Let's say you want the users to see a particular FAQ section, a single FAQ and 2 different Contact Us flows with different prefill texts when they tap the Contact Us buttons within the Helpshift SDK. In this case, you would configure the menuHelpCallback (a button which triggers Helpshift SDK) in the following way :

void AppDelegate::menuHelpCallback(Ref* pSender) {
     ValueVector forms;

    ValueMap faqSectionFlow;
    faqSectionFlow[HS_FLOW_TYPE] = HS_FAQ_SECTION_FLOW;
    faqSectionFlow[HS_FLOW_TITLE] = Value("FAQ Section");
    faqSectionFlow[HS_FLOW_DATA] = "1";
    forms.push_back(Value(faqSectionFlow));

    ValueMap singleFAQFlow;
    singleFAQFlow[HS_FLOW_TYPE] = HS_SINGLE_FAQ_FLOW;
    singleFAQFlow[HS_FLOW_TITLE] = Value("Single FAQ");
    singleFAQFlow[HS_FLOW_DATA] = "2";
    forms.push_back(Value(singleFAQFlow));

    ValueMap conversationFlow1;
    conversationFlow1[HS_FLOW_TYPE] = HS_CONVERSATION_FLOW;
    conversationFlow1[HS_FLOW_TITLE] = Value("Contact us about our app");
    forms.push_back(Value(conversationFlow1));

    ValueMap conversationFlow2;
    conversationFlow2[HS_FLOW_TYPE] = HS_CONVERSATION_FLOW;
    conversationFlow2[HS_FLOW_TITLE] = Value("Contact us about our in-app purchase");
    forms.push_back(Value(conversationFlow2));

    ValueMap showFAQsConfig;
    showFAQsConfig[HS_CUSTOM_CONTACT_US_FLOWS] = Value(forms);
    showFAQsConfig[HS_ENABLE_CONTACT_US] = Value("yes");

    HelpshiftCocos2dx::showFAQs(showFAQsConfig);
}

Anytime the Helpshift SDK is presented via menuHelpCallback with this configuration, the Contact Us buttons in the SDK will redirect to Guided Issue Filing with the flows provided in the HS_CUSTOM_CONTACT_US_FLOWS list.

Once a particular flow is selected, the subsequent Contact Us buttons will not redirect to Guided Issue Filing again. They will function as normal Contact Us buttons. This is to avoid an infinite loop of Guided Issue Filing screens.

Custom flows can be nested by passing another custom flows configuration while creating a flow.

Example :

Let's say you want to configure singleFAQFlow in the above example to show showConversationFlow1 and showConversationFlow2 through the Contact Us buttons inside it. In this case, you would configure the menuHelpCallback button (a button which triggers Helpshift SDK) in the following way :

void AppDelegate::menuHelpCallback(Ref* pSender) {
    ValueVector forms;

    ValueMap faqSectionFlow;
    faqSectionFlow[HS_FLOW_TYPE] = HS_FAQ_SECTION_FLOW;
    faqSectionFlow[HS_FLOW_TITLE] = Value("FAQ Section");
    faqSectionFlow[HS_FLOW_DATA] = "1";
    forms.push_back(Value(faqSectionFlow));

    ValueVector nestedCustomContactUsFlows;

    ValueMap conversationFlow1;
    conversationFlow1[HS_FLOW_TYPE] = HS_CONVERSATION_FLOW;
    conversationFlow1[HS_FLOW_TITLE] = Value("Contact us about our app");
    nestedCustomContactUsFlows.push_back(Value(conversationFlow1));

    ValueMap conversationFlow2;
    conversationFlow2[HS_FLOW_TYPE] = HS_CONVERSATION_FLOW;
    conversationFlow2[HS_FLOW_TITLE] = Value("Contact us about our in-app purchase");
    nestedCustomContactUsFlows.push_back(Value(conversationFlow2));

    ValueMap singleFAQFlowConfig;
    ingleFAQFlowConfig[HS_CUSTOM_CONTACT_US_FLOWS] = Value(nestedCustomContactUsFlows);

    ValueMap singleFAQFlow;
    singleFAQFlow[HS_FLOW_TYPE] = HS_SINGLE_FAQ_FLOW;
    singleFAQFlow[HS_FLOW_TITLE] = Value("Single FAQ");
    singleFAQFlow[HS_FLOW_DATA] = "2";
    singleFAQFlow[HS_FLOW_CONFIG] = Value(singleFAQFlowConfig);
    forms.push_back(Value(singleFAQFlow));

    ValueMap showFAQsConfig;
    showFAQsConfig[HS_CUSTOM_CONTACT_US_FLOWS] = Value(forms);

    HelpshiftCocos2dx::showFAQs(showFAQsConfig);
}

With this configuration, the Contact Us buttons in singleFAQFlow View will redirect to Guided Issue Filing with showConversationFlow1 and showConversationFlow2.

Note

This configuration will work only when there is no open conversation for the user, otherwise every Contact Us button will transition to the chat screen.

Add FAQs to Spotlight search​

Search in iOS 9 gives users great new ways to access information inside of your app. When you make your content searchable, users can access activities and content deep within your app through Spotlight and Safari search results, Handoff, and Siri suggestions. Using APIs related to search, you decide what content gets indexed, what information to show in search results, and where the user is redirected after tapping a result from your app.

The Helpshift SDK can now use these new APIs to add all of your FAQs to the on-device search index. This will ensure that the FAQs that you have added will get maximum visibility. This will also help ensure that your users find solutions to their problems easily and help reduce support issues and eventually churn.

FlagaddFaqsToDeviceSearch
Valuesafter_viewing_faqs / never

after_viewing_faqs : This will add FAQs to the CoreSpotlight index only after the user actually opens the Help section (wired to the showFAQs and showFAQSection APIs).

never : The Helpshift SDK will not add FAQs to the CoreSpotlight index.

For the search entry to launch the appropriate FAQ screen, the application should forward the hand off delegate to Helpshift via the

[HelpshiftSupport handleContinueUserActivity:userActivity withController:viewController andRestorationHandler:restorationHandler]

For example:

ValueMap config;
config[HS_ADD_FAQS_TO_DEVICE_SEARCH] = HS_ADD_FAQS_TO_DEVICE_SEARCH_AFTER_VIEWING_FAQS;
HelpshiftCocos2dx::install("apiKey",
                           "domainName",
                           "appId",
                           config);

enableLogging​

Upon setting enableLogging to true, Helpshift SDK logs will be generated in the Xcode console. This will be useful for debugging the SDK during integration.

Flag:enableLogging
Values:"yes" / "no"
Default:"no"

For example:

ValueMap config;
config[HS_ENABLE_LOGGING] = Value("yes");

HelpshiftCocos2dx::install("apikey",
                           "domain.helpshift.com",
                           "appId",
                           config);

disableErrorReporting​

Disables reporting of Helpshift SDK’s internal error logs. The Helpshift SDK will collect internal error level logs and report them to our systems to ensure that we become aware of runtime issues and we have enough information to fix them.

Option:disableErrorReporting
Values:"yes" / "no"
Default:"no"
Min SDKv5.3.0
Supported by:installForApiKey:domainName:appID:

Example:

ValueMap config;
config[HS_DISABLE_ERROR_REPORTING] = Value("yes");

HelpshiftCocos2dx::install("apikey",
                           "domain.helpshift.com",
                           "appId",
                           config);

enableTypingIndicator​

A graphical indicator is shown to the end user if an Agent is currently replying on the same conversation.

Note

Typing indicator will be enabled only for issues filed with Cocos2d-x v1.7.0 and above.

This SDK configuration has been deprecated since this configuration has shifted to the In-App SDK configuration page. (Settings>App settings)

For Cocos2d-x v4.0.0 and above, Typing Indicator configuration ("Show Agent Typing Indicator") is a part of In-app SDK configurations page.

If configuration is turned ON from the configurations page OR SDK configuration is used, Typing Indicator will shown to the end users.

The HS_ENABLE_TYPING_INDICATOR flag will enable/disable the aforementioned indicator.

Flag:enableTypingIndicator
Values:"yes" / "no"
Default:"no"

For example:

ValueMap config;
config[HS_ENABLE_TYPING_INDICATOR] = Value("yes");
Helpshiftcocos2dx::showFAQs(config);

IssueDescriptionMinimumCharacterLength​

To control the minimum number of characters that the users need to type before they can start a conversation, use this option and set it to an appropriate integer value. This option works both in Conversational issue-filing and Form-based issue-filing experience. Since this option is dependent on the language in which the user starts a conversation, developers are encouraged to set this value for each language as appropriate.

Note

This option is not an SDK API config but rather a key in the HelpshiftLocalizable.strings file.

Configuration Summary​

Option / APIshowFAQsshowFAQSectionshowSingleFAQshowConversation
enableContactUsSupportedSupportedSupportedNot Supported
gotoConversationAfterContactUsSupportedSupportedSupportedSupported
presentFullScreenOniPadSupportedSupportedSupportedSupported
requireEmailSupportedSupportedSupportedSupported
hideNameAndEmailSupportedSupportedSupportedSupported
conversationPrefillTextNo effectNo effectNo effectSupported
enableFullPrivacySupportedSupportedSupportedSupported
showSearchOnNewConversationNo effectNo effectNo effectSupported
showConversationResolutionQuestionSupportedSupportedSupportedSupported
customContactUsFlowsSupportedSupportedSupportedNot Supported
helpshiftFAQSpotlightSearchNot SupportedNot SupportedNot SupportedNot Supported
enableLoggingNot SupportedNot SupportedNot SupportedNot Supported
enableInboxPollingNot SupportedNot SupportedNot SupportedNot Supported
enableTypingIndicatorSupportedSupportedSupportedSupported