Tracking Android

Track events and user actions when the user starts a new conversation. Attach custom metadata to every conversation started via the SDK.

Name and email

Applicable to SDK v3.0.0 and above

You can set the name and email for the user, using setNameAndEmail. For example:

HelpshiftCocos2dx::setNameAndEmail("John Doe", "");
API Reference:


The SDK prefills the previously used name and email in the new conversation screen. If you want to clear these prefilled fields, set both arguments to NULL (applicable to version 3.4.0 and above).

HelpshiftCocos2dx::setNameAndEmail(NULL, NULL);

The name and email shows up in the issue's sidebar in the agent dashboard -


The users can change their name and email in the new conversation screen.

User Identifier

If you have an identification for your users, you can specify that as well using login. For example:

HelpshiftCocos2dx::login("unique-user-id-746501", "John Doe", "");
API Reference:

This shows up in the issue's sidebar in the agent dashboard -


User identifier should always be unique for each user.

In issue sidebar in the agent dashboard, other issues by the same user are also matched using user identifier. So make sure it is unique for each user.


Multi Login

Applicable to plugin v3.8.0 and above

These APIs give developers the ability to allow multiple users to chat with agents on the same app

Logging in

You can login a user via login API.

The identifier uniquely identifies the user. Name and email are optional. It is the app developer's responsibility to make sure that the identifier is unique.

For example:

HelpshiftCocos2dx::login("unique-user-id-746501", "John Doe", "");

Logging out

The logout API will logout the currently logged in user. After logout, Helpshift falls back to the default login.

For example:


Important notes

  • If you are passing in user-login dependent meta-data, please make sure you reset the meta-data through the Helpshift APIs when you change the login.
  • If you are using the leaveBreadCrumb API to pass user login related crumbs, please make sure to call the clearBreadCrumsbs API when you change the login.
  • After logout, user can still submit a new conversation, but it will be with the device credentials
  • If any of the helpshift screens is currently being shown in the app, then any login/logout attempt is ignored.
  • If login api is called with different user identifier, then it first logs out the currently logged in user and then logs in with this user identifier.
  • Use setNameAndEmail only if login is not being used.
  • If setNameAndEmail is used when already logged in, then it will overwrite the logged in user name and email.
  • setUserIdentifier does not relate to user login.
  • It is best to call login immediately when your app user logs in.

App usage

Breadcrumbs will help you track events or user actions and when user starts a new conversation, these breadcrumbs can be seen along with the conversation in the admin site. To leave breadcrumbs can use leaveBreadCrumb. For example:

HelpshiftCocos2dx::leaveBreadCrumb("Went to Preferences Screen");
API Reference:

Breadcrumbs will be collected within the set breadcrumb limit. This is set in the SDK Configurations section for app settings in the agent dashboard. Breadcrumbs are collected in a FIFO queue. If you want to clear the breadcrumbs queue, please use the clearBreadCrumbs api call. For example:

API Reference:

Attaching metadata to reported issues

You can attach additional metadata to every new conversation started by the app user via a very simple mechanism provided by the SDK. This metadata can range from user-name, email etc to game scores, current game levels and any other data relevant to creating a suitable context to each new conversation.

In all the api calls which launch the Help section, you can add a meta-data dictionary in the config dictionary parameter using the HS_META_DATA_KEY macro. This meta-data will be sent along with the next reported issue. When the user exits out of the Help section this meta-data will be dropped in favor of the meta-data sent in the next Helpshift API call.

Attaching tags with metadata

On tag names & compatibility

  • Tags must be lowercase.
  • Please do ensure that the tags you send via meta data, are exact matches of tags that exist in the admin site.


You can attach tags with metadata to every reported issue via the HS_TAGS_KEY macro. This is used with the config dictionary as follows:

For cocos2d-x 3.x

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

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

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

For cocos2d-x 2.x

cocos2d::CCDictionary *config = new cocos2d::CCDictionary();
cocos2d::CCDictionary *meta = new CCDictionary();
meta->setObject(new CCString("54$"), "Money spent");

cocos2d::CCArray *tags = new cocos2d::CCArray();
tags->addObject (new CCString("Whale"));
tags->addObject (new CCString("Cocos2d-x"));

meta->setObject(tags, HS_TAGS_KEY);
config->setObject(meta, HS_META_DATA_KEY);

Attaching Custom Issue Fields to conversations

Applicable to SDK v1.8.0 and above.

You can attach Custom Issue Fields to every new conversation started by the app user. A Custom Issue Field should have a key, a datatype, and a value. The SDK allows the addition of Custom Issue Fields by using the setCustomIssueFields method with the config dictionary passed to the SDK APIs.

These Custom Issue Fields would be sent whenever a new issue is created.

Possible datatypes to be passed into the config are:

Type Comments
"sl" Single line string with character limit of 255
"ml" Multi line string with character limit of 100,000
"n" String representation of number. For eg. "12345"
"dd" Drop-down options should exist for the given Custom Issue Field on dashboard. Value should be one of the values specified on the dashbaord for that dropdown.
"dt" String representation of epoch time in milliseconds. For eg. "1505927361535"
"b" String representation of boolean. For eg. "true" or "false". This corresponds to the checkbox type custom issue field on dashboard.

For example:

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

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

    ValueVector integerData;
    customIssueFields["level"] = Value(integerData);

    ValueVector booleanData;
    customIssueFields["is_pro"] = Value(booleanData);

    ValueVector dropdownData;
    customIssueFields["currency"] = Value(dropdownData);

    ValueVector dateData;
    customIssueFields["join_date"] = Value(dateData);

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


    cocos2d::CCDictionary *customIssueFields = new CCDictionary();

    cocos2d::CCArray *singleLineStringCIF = new cocos2d::CCArray();
    singleLineStringCIF->addObject (new CCString("sl"));
    singleLineStringCIF->addObject (new CCString("John Doe"));
    customIssueFields->setObject(singleLineStringCIF, "employee_name");

    cocos2d::CCArray *multiLineCIF = new cocos2d::CCArray();
    multiLineCIF->addObject (new CCString("ml"));
    multiLineCIF->addObject (new CCString("3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"));
    customIssueFields->setObject(multiLineCIF, "employee_address");

    cocos2d::CCArray *numberCif = new cocos2d::CCArray();
    numberCif->addObject (new CCString("n"));
    numberCif->addObject (new CCString("5"));
    customIssueFields->setObject(numberCif, "stock_level");

    cocos2d::CCArray *checkboxCif = new cocos2d::CCArray();
    checkboxCif->addObject (new CCString("b"));
    checkboxCif->addObject (new CCString("true"));
    customIssueFields->setObject(checkboxCif, "is_pro");

    cocos2d::CCArray *dropdownCif = new cocos2d::CCArray();
    dropdownCif->addObject (new CCString("dd"));
    dropdownCif->addObject (new CCString("Dollars"));
    customIssueFields->setObject(dropdownCif, "salary_currency");

    cocos2d::CCArray *dateCif = new cocos2d::CCArray();
    dateCif->addObject (new CCString("dt"));
    dateCif->addObject (new CCString("1505927361535"));
    customIssueFields->setObject(dateCif, "joining_date");

    config->setObject(customIssueFields, HS_CUSTOM_ISSUE_FIELDS);


Debug logs

If you want to add debug logs at specific places within your application which will help you debug issues filed by the user, you can use the log functions of the Helpshift class which will provide varying degress of logging. For example, if you want to attach debug level logs please add the following code

HelpshiftCocos2dx::logd("Helloworld", "This is the number : %d", 123);

Issue Archival

From version 1.3.0, Helpshift SDK includes support for archiving issues. Issues in Resolved or Rejected state for more than 12 months will be automatically archived. Once archived, issues cannot be reopened. This improves dashboard performance. Archived issues will be accessible to agents through the dashboard for future reference.


Check if an active Conversation exists

Applicable to SDK v1.7.0 and above.

You can check if the user has any active Conversations on the device with HelpshiftCocos2dx::checkIfConversationActive(...) API. A Conversation is considered active when the user can go to the Conversation screen and respond with new messages on it.

For Example:

void conversationActive(bool isActive) {
    if (isActive == "true") {
        // Active Conversation.
    } else {
        // No open Conversation.