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 Helpshift.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 Helpshift.showConversation(this, 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:

Map<String, Object> config = new HashMap<>();
config.put("tags", new String[]{"foo", "bar"});
Helpshift.showConversation(MainActivity.this, config);

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:

HashMap<String, String> customMetadata = new HashMap<String, String();
customMetadata.put("usertype","paid");
customMetadata.put("level","7");
customMetadata.put("score","12345");

HashMap<String, Object> config = new HashMap<>();
config.put("customMetadata", customMetadata);

Helpshift.showConversation(MainActivity.this, 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.

HashMap<String, String> customMetadata = new HashMap<String, String();
HashMap<String, Object> config = new HashMap<>();
config.put("customMetadata", customMetadata);
Helpshift.showConversation(MainActivity.this, 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.

Note

The "customIssueFields" key has been deprecated. We strongly recommend transitioning to using the "cifs" key as the preferred method for passing custom issue fields.

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:

1. Initialise a top level custom issue fields' Map
2. For each custom issue field, define your custom issue field Map
3. Add the "type" and "value" for that custom issue field in custom issue field map.
4. Add the custom issue field map to top level map (with key as your configured key and value as custom issue field map)
5. Pass the map to configMap with key "cifs" of the Helpshift.showConversation(this, configMap)

Map<String, Object> joiningDate = new HashMap<>();
joiningDate.put("type", "date");
joiningDate.put("value", 1505927361535L);

Map<String, String> stockLevel = new HashMap<>();
stockLevel.put("type", "number");
stockLevel.put("value", "1505");

Map<String, String> employeeName= new HashMap<>();
employeeName.put("type", "singleline");
employeeName.put("value", "Bugs helpshift");

Map<String, String> isPro = new HashMap<>();
isPro.put("type", "checkbox");
isPro.put("value", "true");

Map<String, Object> cifMap = new HashMap<>();
cifMap.put("joining_date", joiningDate);
cifMap.put("stock_level", stockLevel);
cifMap.put("employee_name", employeeName);
cifMap.put("is_pro", isPro);

Map<String, Object> config = new HashMap<>();
// other configs...
//..
config.put("cifs", cifMap);

Helpshift.showConversation(MainActivity.this, config);

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"	long	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:

Helpshift.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:

Helpshift.clearBreadCrumbs();

Note

• Applicable to SDK X v10.1.0 & above
• 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 com.helpshift.HSDebugLog.

For example:

HSDebugLog.d("TAG", "Any Debug log string");

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

• Applicable to SDK X v10.1.0 & above
• In the HSDebugLog 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 user-specific metadata

Update global user data

This API is meant to be used along with the new User Identity system. Use this API to update global attributes associated with the logged in user.

  Map<String, Object> masterAttributes = new HashMap<>();
  // put appropriate master attribute key and its value
  masterAttributes.put("<master-attribute-key>", "<master-attribute-value>");
  Helpshift.updateMasterAttributes(masterAttributes);

Update app specific user data

This API is meant to be used along with the new User Identity system. Use this API to update app specific attributes associated with the logged in user.

  Map<String, Object> appAttributes = new HashMap<>();
  // put appropriate app attribute key and its value
  appAttributes.put("<app-attribute-key>", "<app-attribute-value>");
  Helpshift.updateAppAttributes(appAttributes);