Skip to main content

Tracking iOS

Important
Helpshift’s Legacy SDKs (SDK Version <=7.x.x) reached their end of life on 31 Dec 2022, and end of support on 31 March 2023. Please upgrade to the Latest SDK if you haven't already.

Tracking iOS

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​

Note

This API is now deprecated with SDK v3.0.

It is expected that you will pass the user's name, email or, user identifier using the Login API.

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​

Note

This API is now deprecated with SDK v3.0.

It is expected that you will pass the user's name, email or, user identifier using the Login API.

Also, please note that there will no impact on older SDK versions, and they will keep on working as usual.

Multi Login​

Details on user management are available here.

Debug logs​

Optionally, if you want to send additional debug logs, use HelpshiftApi.HelpshiftLogger to log messages in all files where you have used Log statements. This will send your logs when a new issue is registered.

Example:


HelpshiftApi.HelpshiftLogger.e("AppLogTag", "Error Log message");
HelpshiftApi.HelpshiftLogger.d("AppLogTag", "Debug log message");

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. For example:

HelpshiftApi.HelpshiftSupport.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. For example:

HelpshiftApi.HelpshiftSupport.ClearBreadCrumbs();

Attaching metadata to reported issues​

You can attach additional metadata to every new conversation started by the app user via two simple mechanisms 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.

Note
  • 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, they see a greeting message, and the conversation is considered active.
  • All the modified metadata (updated during an active conversation) will only be sent with the next conversation that end user starts.

In all the API calls which launch the Help section, you can add a meta-data dictionary in the config dictionary parameter using the HelpshiftApi.HelpshiftSupport.HSCUSTOMMETADATAKEY key. This meta-data will be sent along with the next reported issue. When the user exits out of the Help section this meta-data will be dropped in favor of the meta-data sent in the next Helpshift API call.

Attaching tags with metadata​

Note

On tag names & compatibility

  • Tags must be lowercase.
  • Please do ensure that the tags you send via meta data, are exact matches of tags that exist in the admin site.

Examples :

string[] tags = new string[] { "feedback", "paid user" };
Dictionary<string, object> userData = new Dictionary<string, object>();
userData.Add("usertype", "paid");
userData.Add("level", "7");
userData.Add("score", "12345");
HelpshiftSupportMetadata metadata = new HelpshiftSupportMetadata(userData, tags);
HelpshiftAPIConfig apiConfig = new HelpshiftAPIConfig.Builder()
                                                     .SetCustomMetadata(metadata)
                                                     .Build();
HelpshiftApi.HelpshiftSupport.ShowFAQs(this, apiConfig);

Attaching Custom Issue Fields to conversations​

Note

On Custom Issue Fields keys & compatibility

  • Applicable to SDK v2.5.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 a dictionary of Custom Issue Fields by using the SetCustomIssueFields method in the HelpshiftAPIConfig class. These Custom Issue Fields would be sent whenever a new issue is created by the end user.

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.

Possible datatypes to be passed into the config are:

TypeComments
"sl"Single line string with character limit of 255
"ml"Multi line string with character limit of 100,000
"n"String representation of a 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.
Dictionary<string, string[]> customIssueFields = new Dictionary<string, string[]>();

// The format for calling Add is customIssueFields.Add(<key>, new string[]{<datatype>, <value>});
customIssueFields.Add("join_date", new string[]{"dt", "1505927361535"});
customIssueFields.Add("level", new string[]{"n", "42"});
customIssueFields.Add("name", new string[]{"sl", "John Doe"});
customIssueFields.Add("address", new string[]{"ml", "3346, Sunny Glen Lane,
                                               Warrensville Heights, Ohio - 44128"});
customIssueFields.Add("is_pro", new string[]{"b", "true"});
customIssueFields.Add("currency", new string[]{"dd", "Dollar"});

HelpshiftAPIConfig apiConfig = new HelpshiftAPIConfig.Builder()
                                                     .SetCustomIssueFields(customIssueFields)
                                                     .Build();
HelpshiftApi.HelpshiftSupport.ShowFAQs(activity, apiConfig);

Check if there is an active Conversation​

Note

Applicable to SDK v2.4.0 and above

This API determines if there is currently an ongoing Conversation in the SDK. You can use "HelpshiftApi.HelpshiftSupport.CheckIfConversationActive()" and implement Helpshift delegate DidCheckIfConversationActive method as shown below to get a boolean value that indicates whether there is an active Conversation open for the user. A Conversation is considered inactive when a user cannot respond with new messages on it.

As soon as an end user opens the conversation screen, they see a greeting message, and the conversation is considered active.

For example:


    HelpshiftApi.HelpshiftSupport.CheckIfConversationActive();

You can implement the "DidCheckIfConversationActive" delegate method like the following example:


    public class  HSDelegate : InternalHsApiDefinition.HelpshiftSupportDelegate {

    .
    .
    .
    .
    .
    .

        public void DidCheckIfConversationActive(bool isActive) {
            // your code here
        }

    }

Check if an active Conversation has ended​

If you want to keep track of when your users end an ongoing conversation, you can implement this delegate callback. This delegate is called whenever the ongoing conversation is resolved, rejected from the Dashboard, timed out or archived.


    public override void ConversationEnded() {
        // Conversation has ended
    }