Tracking

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

Note

All the public APIs in the SDK should be called after initializing the SDK via install API

Adding Tags to Conversations

You can attach tags while reporting an issue by passing them to the configMap object at the time of calling HelpshiftCocos2dx::showConversation(configMap). You can pass an array of strings with a key "tags" which will get added as Tags when the issue is created.

For example:

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

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

    configMap["tags"] = tags;
    return configMap;
}

cocos2d::ValueMap chatConfig = getConfig();
HelpshiftCocos2dx::showConversation(chatConfig);

Note

On tag names & compatibility

Tags must be pre-created in the Helpshift Dashboard (Settings → Tags), otherwise they will be ignored.
The attached tags must exactly match the tags present on the dashboard.

Adding Custom Metadata to Conversations

You can attach additional metadata to every new conversation started by the app user. This metadata can include properties like username, email, game scores, current game levels, and any other data needed to provide relevant context for each new conversation. You can attach custom metadata by passing it to the configMap object at the time of calling any of the SDK X APIs (showConversation, showFAQs, showSingleFAQ, showFAQSection).

Example:

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

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

HelpshiftCocos2dx::showFAQs(config);

Note

Metadata should only be sent as String key-value pairs.
Once customMetadata is set, if you want to reset it, then you’ll have to call the SDK X API with an empty map, i.e.

ValueMap config;
ValueMap meta;
config["customMetadata"] = Value(meta);
HelpshiftCocos2dx::showFAQs(config);

Attaching Custom Issue Fields to conversations

You can attach Custom Issue Fields to every new conversation started by the user. A Custom Issue Field should have a key, a datatype, and a value. The Helpshift SDK allows the addition of Custom Issue Fields by using the cifs key in API config map.

These custom issue fields will be sent whenever an end user starts a new conversation or creates an issue via Smart FAQs.

As soon as an end user opens the conversation screen, they see a greeting message, and the conversation is considered active. All the modified Custom Issue Fields (updated during an active conversation) will only be sent with the next conversation that end user starts.

If you want to set Custom Issue Fields at the time of Issue creation, follow the steps:

Initialise a top level custom issue fields' ValueMap
For each custom issue field, define your custom issue field ValueMap
Add the "type" and "value" for that custom issue field in custom issue field map.
Add the custom issue field map to top level map (with key as your configured key and value as custom issue field map)
Pass the map to configMap with key "cifs" of the HelpshiftCocos2dx::showConversation(configMap)

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

cocos2d::ValueMap chatConfig = getConfig();
  HelpshiftCocos2dx::showConversation(chatConfig);

Possible datatypes to be passed into the config are:

Type	value	Comments
"singleline"	string	Single line string with character limit of 255
"multiline"	string	Multi line string with character limit of 100,000
"number"	string	String representation of number. For eg. "12345"
"dropdown"	string	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.
"date"	string	String representation of Epoch time in milliseconds, For eg. "1505927361535"
"checkbox"	string	String representation of boolean. For eg. "true" or "false". This corresponds to the checkbox type custom issue field on dashboard.

Note

On Custom Issue Fields keys & compatibility

Custom Issue Fields must be created in the Helpshift Dashboard (Settings → Custom Issue Fields), otherwise they will be ignored. Read more here.

Breadcrumbs

Breadcrumbs can be used to track events or end-user actions. It helps you to add debugging information regarding end-user actions, which will be passed along with every new conversation on Helpshift’s Agent Dashboard. To leave breadcrumbs, use leaveBreadCrumb API —

For example:

HelpshiftCocos2dx::leaveBreadCrumb("Any breadcrumb string");

Breadcrumbs are collected within the set breadcrumb limit. The limit is set under the SDK Configurations section for App Settings in the Helpshift’s Agent Dashboard. Breadcrumbs are collected in a FIFO queue. If you want to clear the breadcrumbs, use the clearBreadCrumbs API —

For example:

HelpshiftCocos2dx::clearBreadCrumbs();

Note

In the leaveBreadcrumb API, passing of formatted strings is NOT supported. It is recommended to pass data only in a simple String format. For example:
- "{\"key\":\"value\"}" - JSON String, This is NOT supported
- "key - value" - Simple string, This is supported

Debug Logs

You may wish to pass additional debug logs with every new conversation filed by an end-user on Helpshift’s Agent Dashboard. This can be achieved by using HelpshiftLog.

For example:

HelpshiftLog::d("<debug-tag>", "<debug-message>");

Debug logs are collected within the set debug logs limit. The limit is set under the SDK Configurations section for App Settings in the Helpshift’s Agent Dashboard. Debug logs are collected in a FIFO queue.

Note

In the HelpshiftLog API, passing of formatted strings is NOT supported. It is recommended to pass data only in a simple String format. For example:
- "{\"key\":\"value\"}" - JSON String, This is NOT supported
- "key - value" - Simple string, This is supported

Tracking

Adding Tags to Conversations​

Adding Custom Metadata to Conversations​

Attaching Custom Issue Fields to conversations​

Breadcrumbs​

Debug Logs​

Adding Tags to Conversations

Adding Custom Metadata to Conversations

Attaching Custom Issue Fields to conversations

Breadcrumbs

Debug Logs