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 setUserIdentifier

For example:

Support.setUserIdentifier("APAC-02201-TH");

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

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 (Optional)

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 to reported issues

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

Debug logs

Optionally, if you want to send additional debug logs, Replace import android.util.Log with import com.helpshift.Log in all files where you have used Log statements. This will send your logs when a new issue is registered. com.helpshift.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