Tracking
Tracking
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
This API is now deprecated with SDK v7.0.0
It is expected that developers will pass the Name, Email or User Identifier using the Login API <link to User Identification> going forward.
Also, please note that this API will not work with the Conversational Experience. However, there will no impact on older SDK versions. They will keep on working as usual.
User Identifier
This API is now deprecated with SDK v7.0.0
It is expected that developers will pass the Name, Email or User Identifier using the Login API going forward.
Also, please note that there will no impact on older SDK versions and that they will keep on working as usual.
Multi Login
Details on User management are available here
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:
Support.leaveBreadCrumb("Went to Preferences Screen");
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.
Support.clearBreadCrumbs();
Attaching 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 metadata to every new conversation in one of two ways:
In case both methods are used, and then the metadata from the last accessed method will be sent when creating a new conversation. For example, if metadata is sent with the showFAQs() API, and the metadata callback is set from a background thread after the showFAQs() API call, then metadata from the metadata callback will be sent with the new conversation.
While metadata can be set anytime, it will only be sent to the agent dashboard when customer starts a new conversation.
As soon as an end user opens the conversation screen, that end user will see a greeting message, and the conversation is considered active.
Any modified metadata (updated during an active conversation) will only be sent within the next conversation that the end user starts.
Attaching metadata with API configuration
Metadata using API config is available in SDK v3.1.0 and above. Also, Metadata should only be sent as String key-value pairs.
The Android SDK allow adding of metadata by using Metadata object in the ApiConfig object
showConversationshowFAQsshowFAQSectionshowSingleFAQ
The SDK will send data which is given as Metadata in ApiConfig for the new conversation.
Example:-
- Using Metadata and ApiConfig
- Using Map
String[] tags = new String[]{"feedback", "paid user"};
HashMap<String, Object> userData = new HashMap<>();
userData.put("usertype", "paid");
userData.put("level", "7");
userData.put("score", "12345");
Metadata metadata = new Metadata(userData, tags);
private void showHelp () {
ApiConfig apiConfig = new ApiConfig.Builder()
.setCustomMetadata(metadata)
.build();
Support.showFAQs(MainActivity.this, apiConfig);
}
The Android SDK also allows adding of metadata by using reserved constant key Support.CustomMetadataKey in the API Configuration HashMap.
String [] tags = new String[]{"feedback", "paid user"};
HashMap customMetadata = new HashMap();
customMetadata.put("usertype","paid");
customMetadata.put("level","7");
customMetadata.put("score","12345");
customMetadata.put(Support.TagsKey, tags);
private void showHelp() {
HashMap config = new HashMap ();
config.put ("enableContactUs", preferences.getBoolean("enableContactUs", true));
config.put(Support.CustomMetadataKey, customMetadata);
Support.showFAQs(MainActivity.this, config);
}
Attaching metadata with metadata callback
Metadata should only be sent as String key-value pairs.
In order to facilitate the adding of such metadata the Android SDK
provides a method to set MetadataCallable, which is called right before
sending the new conversation message to agent dashboard. The SDK will send
along the data returned from this callable as metadata for the reported
issue.
Developers can use the setMetadataCallback API to provide a MetadataCallable object with call method implemented to return an object of Metadata containing the key-value pairs and tags which make up the metadata.
Example:-
- Using MetadataCallable
- Using HashMap Callable
import com.helpshift.support.MetadataCallable;
Support.setMetadataCallback (new MetadataCallable (){
public Metadata call() {
HashMap<String, Object> userMetadata = new HashMap<>();
userMetadata.put("name", "John");
userMetadata.put("email", "john@example.com");
userMetadata.put("level", gameObject.getLevel());
userMetadata.put("score", gameObject.getScore());
String[] tags = new String[]{"feedback", "paid user"};
return new Metadata(userMetadata, tags);
}
});
import com.helpshift.support.Callable;
Support.setMetadataCallback (new Callable (){
public HashMap call() {
String[] tags = new String[]{"feedback", "paid user"};
HashMap userMetadata = new HashMap();
userMetadata.put("name", "John");
userMetadata.put("email", "john@example.com");
userMetadata.put("level", gameObject.getLevel());
userMetadata.put("score", gameObject.getScore());
userMetadata.put(Support.TagsKey, tags);
return usermetadata;
}
});
Attaching tags with metadata
On tag names & compatibility
- Applicable to SDK v 2.8.0 & above.
- Tags must be lowercase.
- Please do ensure that the tags you send via meta data, match the tags that exist in the agent dashboard.
You can attach tags with metadata to every reported issue by passing them to Metadata object. You can pass an array of strings which get interpreted
at server and added as Tags for the every issue reported.
- Using Metadata and ApiConfig
- Using Map
String[] tags = new String[]{"feedback", "paid user"};
HashMap<String, Object> userData = new HashMap<>();
userData.put("usertype", "paid");
userData.put("level", "7");
userData.put("score", "12345");
Metadata metadata = new Metadata(userData, tags);
private void showHelp () {
ApiConfig apiConfig = new ApiConfig.Builder()
.setCustomMetadata(metadata)
.build();
Support.showFAQs(MainActivity.this, apiConfig);
}
You can attach tags with metadata to every reported issue via a reserved key constant Support.TagsKey to be used with setMetadataCallback to pass an array of strings which get interpreted at server and added as Tags for the every issue reported.
String [] tags = new String [] ("feedback", "paid user");
HashMap customMetadata = new HashMap();
customMetadata.put("name","John");
customMetadata.put("email","john@example.com");
customMetadata.put(Support.TagsKey, tags);
private void showHelp() {
HashMap config = new HashMap ();
config.put ("enableContactUs", preferences.getBoolean("enableContactUs", true));
config.put(Support.CustomMetadataKey, customMetadata);
Support.showFAQs(MainActivity.this, config);
}
Attaching Custom Issue Fields to conversations
On Custom Issue Fields keys & compatibility
- Applicable to SDK v6.3.0 & above.
- Custom Issue Fields must be created in the Helpshift Dashboard (Settings -> Custom Issue Fields), otherwise they will be ignored. Read more here.
You can attach Custom Issue Fields to every new conversation started by the user. A Custom Issue Field should have a key, a data type, and a value. The SDK allows the addition of Custom Issue Fields by using the setCustomIssueFields method in the ApiConfig class.
These Custom Issue Fields would be sent whenever a new issue is created.
As soon as an end user opens the conversation screen, they will see a greeting message, and the conversation is considered active.
Any modified Custom Issue Fields (updated during an active conversation) will only be sent within the next conversation that the end user starts.
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. |
Example:-
- Using ApiConfig
- Using Map
Map<String, String[]> customIssueFields = new HashMap<>();
// The format for calling put is customIssueFields.put(<key>, new String[]{<datatype>, <value>});
customIssueFields.put("join_date", new String[]{"dt", "1505927361535"});
customIssueFields.put("level", new String[]{"n", "42"});
customIssueFields.put("name", new String[]{"sl", "John Doe"});
customIssueFields.put("address", new String[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
customIssueFields.put("is_pro", new String[]{"b", "true"});
customIssueFields.put("currency", new String[]{"dd", "Dollar"});
private void showHelp() {
ApiConfig apiConfig = new ApiConfig.Builder()
.setCustomIssueFields(customIssueFields)
.build();
Support.showFAQs(MainActivity.this, apiConfig);
}
The SDK also allows adding of custom issue fields by using reserved constant key Support.CustomIssueFieldKeyin the API Configuration HashMap.
Map<String, String[]> customIssueFields = new HashMap<>();
// The format for calling put is customIssueFields.put(<key>, new String[]{<datatype>, <value>});
customIssueFields.put("join_date", new String[]{"dt", "1505927361535"});
customIssueFields.put("level", new String[]{"n", "42"});
customIssueFields.put("name", new String[]{"sl", "John Doe"});
customIssueFields.put("address", new String[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
customIssueFields.put("is_pro", new String[]{"b", "true"});
customIssueFields.put("currency", new String[]{"dd", "Dollar"});
private void showHelp() {
Map<String, Object> config = new HashMap<>();
config.put(Support.CustomIssueFieldKey, customIssueFields);
Support.showFAQs(MainActivity.this, config);
}
Debug logs
Optionally, if you want to send additional debug logs, Replace import
android.util.Log with import com.helpshift.support.Log in all files where you
have used Log statements. This will send your logs when a new issue is
registered. com.helpshift.support.Log can be used as android.util.Log.
Issue Archival
From version 4.6.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 there exists an active Conversation
Applicable to SDK v4.9.0 and above
You can check if the user has any active Conversation on the device with isConversationActive. As soon as an end user opens the conversation screen, they will see a greeting message, and the conversation is considered active.
For example:
if (Support.isConversationActive()) {
//Your code here
} else {
//Your code here
}