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 SDKif 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​

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

For example:

HelpshiftCocos2dx::setNameAndEmail("John", "john@example.com");

The SDK prefills the previously used name and email in the new conversation screen. If you want to clear these fields, please use the setNameAndEmail API with both params set to NULL.

For example:

HelpshiftCocos2dx::setNameAndEmail(NULL, NULL);

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

Note

This API is now deprecated with cocos2d-x SDK v4.0.

It is expected that developers will pass the Name, Email or User Identifier using the login API 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​

If have an identification for your users, you can specify that as well using login.

For example:

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

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

Important

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.

notes

This API is now deprecated with cocos2d-x SDK v4.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​

Note

Applicable to plugin v4.10.0 and above

These APIs give developers the ability to allow multiple users to chat with agents on the same app

Logging in​

Note

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

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

HelpshiftCocos2dx::clearBreadCrumbs();

Attaching metadata to reported issues​

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.

In all the API calls which launch the Help section, you can add a meta-data dictionary in the config dictionary parameter using the HS_META_DATA_KEY 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.

For example :

    ValueMap config;
    ValueMap meta;
    meta["usertype"] = Value("paid")
    meta["level"] = Value("7")
    meta["score"] = Value("12345")

    config[HS_META_DATA_KEY] = Value(meta)
    HelpshiftCocos2dx::showFAQs(config);

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.

You can attach tags with metadata to every reported issue via a reserved key constant HS_TAGS_KEY. This is used with the config dictionary.

For example:

    ValueMap config;
    ValueMap meta;
    meta["usertype"] = Value("paid")
    meta["level"] = Value("7")
    meta["score"] = Value("12345")

    ValueVector tags;
    tags.push_back("feedback")
    tags.push_back("paid user")

    meta[HS_TAGS_KEY] = Value(tags)
    config[HS_META_DATA_KEY] = Value(meta)
    HelpshiftCocos2dx::showFAQs(config)
Note

While metadata can be set anytime, it will only be sent to the Admin Dashboard when an end user 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 Custom Issue Fields to conversations​

Note

On Custom Issue Fields keys & compatibility

  • Applicable to SDK v1.8.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 datatype, and a value. The Helpshift SDK allows the addition of Custom Issue Fields by using the HS_CUSTOM_ISSUE_FIELDS key in the config object. 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:

TypevalueComments
"sl"stringSingle line string with character limit of 255
"ml"stringMulti line string with character limit of 100,000
"n"stringString representation of number. For eg. "12345"
"dd"stringDrop-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"stringString representation of epoch time in milliseconds. For eg. "1505927361535"
"b"stringString representation of boolean. For eg. "true" or "false". This corresponds to the checkbox type custom issue field on dashboard.

Example:-

    ValueMap config;
    ValueMap customIssueFields;

    ValueVector numberCif;
    numberCif.push_back(Value("n"));
    numberCif.push_back(Value("5"));

    ValueVector dateCif;
    dateCif.push_back(Value("dt"));
    dateCif.push_back(Value("1505927361535"));

    ValueVector singleLineStringCIF;
    singleLineStringCIF.push_back(Value("sl"));
    singleLineStringCIF.push_back(Value("John Doe"));

    ValueVector multiLineCIF;
    multiLineCIF.push_back(Value("ml"));
    multiLineCIF.push_back(Value("3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"));

    ValueVector checkboxCif;
    checkboxCif.push_back(Value("b"));
    checkboxCif.push_back(Value("true"));

    ValueVector dropdownCif;
    dropdownCif.push_back(Value("dd"));
    dropdownCif.push_back(Value("Dollars"));

    customIssueFields["joining_date"] = Value(dateCif);
    customIssueFields["stock_level"] = Value(numberCif);
    customIssueFields["employee_name"] = Value(singleLineStringCIF);
    customIssueFields["employee_address"] = Value(multiLineCIF);
    customIssueFields["is_pro"] = Value(checkboxCif);
    customIssueFields["salary_currency"] = Value(dropdownCif);

    config[HS_CUSTOM_ISSUE_FIELDS] = customIssueFields;
    HelpshiftCocos2dx::showFAQs(config);

Debug logs​

Note

Starting iOS 10, Apple has deprecated support for the ASL library that was used to collect logs from the system automatically.

You may wish to send additional debug logs when an issue is filed. This can be acheived using HelpshiftCocos2dx's log: API.

static void log(const char *message);

For example:

void MyGame::buyGems() {
    ...
    HelpshiftCocos2dx::log("User has bought gems");
    ...
}

When an issue is filed by the user, these debug logs will be submitted as metadata.

Issue Archival​

From version 5.7.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 is an active Conversation​

Note

Applicable to SDK v1.7.0 and above.

You can check if the user has any active Conversation on the device with HelpshiftCocos2dx::checkIfConversationActive(...) API. As soon as an end user opens the conversation screen, they will see a greeting message, and the conversation is considered active.

For example:

void conversationActive(bool isActive) {
    CCLOG("HelpshiftCocos2dx::checkIfConversationActive : %s", isActive ? "true" : "false");
}
HelpshiftCocos2dx::checkIfConversationActive(conversationActive);