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

Applicable to SDK v3.0.0 and above

You can set the name and email for the user, using setNameAndEmail

For example:

Core.setNameAndEmail("John Doe", "john.doe@johndoe.com");

username-email-sdk.png

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).

Core.setNameAndEmail(null, null);

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

username-email-admin.png

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:

Core.login("APAC-02201-TH", "John Doe", "john.doe@johndoe.com");

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

user-id-admin.png

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.

other-issues-by.png

Multi Login

Applicable to SDK 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

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:

Core.login("unique-user-id-746501", "John Doe", "john.doe@app.co");

Logging out

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

For example:

Core.logout();

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 clearBreadCrumbs 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:

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.

Attaching metadata with API configuration

Metadata using API config is available in SDK v3.1.0 and above.

The Android SDK allow adding of metadata by using Metadata object in the ApiConfig object

The SDK will send data which is given as Metadata in ApiConfig for the new conversation.

Example:-

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

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

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.

metadatatags.png

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.

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.

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

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.

issueArchival.png

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. A Conversation is considered active when user can go to the Conversation screen and respond with new messages on it.

For example:

if (Support.isConversationActive()) {
    //Your code here
} else {
    //Your code here
}