Looking for older SDK 3.X docs? Click here →

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

You can set the name and email for the user, using setName:andEmail:

For example:

[HelpshiftCore setName:@"John Doe" andEmail:@"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 nil (applicable to version 4.5.0 and above).

[HelpshiftCore setName:nil andEmail:nil];

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:

[HelpshiftSupport setUserIdentifier:@"APAC-02201-TH"];

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

user-id-admin.png

If you have an external dashboard to manage your Users, you can also link the User ID in Helpshift to the User’s page in your dashboard. Use {user_id} variable to create user specific links. For example, the link http://company.com/users/{user_id} will result in something like http://company.com/345678

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 v4.10.0 and above

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

Logging in

You can login a user via loginWithIdentifier:withName:andEmail:

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:

[HelpshiftCore loginWithIdentifier:@"unique-user-id-746501" withName:@"John Doe" andEmail:@"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:

[HelpshiftCore logout];

Important notes

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:

[HelpshiftSupport leaveBreadCrumb:@"Custom String"];

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.

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.

Adding metadata with API options

The iOS SDK allows adding of metadata by using reserved constant key HelpshiftSupportCustomMetadataKey and NSDictionary as its value in withOptions: param of support API's,

The SDK will send data which is given as NSDictionary in options as custom data for the new conversation.

Example usages:

HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customMetaData = [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"usertype":@"paid", @"level":@"7", @"score":@"12345"} 
                                                                    andTags:@[@"feedback",@"paid user",@"v4.1"]];
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfigs:apiConfig];
HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customMetaData = [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"usertype":@"paid", @"level":@"7", @"score":@"12345"}];
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfigs:apiConfig];

NSDictionary *metaDataWithTags = @{@"usertype": @"paid",
                                   @"level":@"7",
                                   @"score":@"12345",
                                   HelpshiftSupportTagsKey:@[@"feedback",@"paid user",@"v4.1"]};

[HelpshiftSupport showFAQs:self
               withOptions:@{@"gotoConversationAfterContactUs":@"YES",
       HelpshiftSupportCustomMetadataKey: metaDataWithTags}];
NSDictionary *metaData = @{@"usertype": @"paid", @"level":@"7", @"score":@"12345"]};

[HelpshiftSupport showConversation:self
                       withOptions:@{HelpshiftSupportCustomMetadataKey: metaData}];

Adding metadata using setMetadataBlock API

Developers can still use the setMetadataBlock: api to provide a block which returns an NSDictionary object containing the key-value pairs which make up the metadata.The signature of the metadataBlock is typedef NSDictionary* (^metadataBlock)(void);

[HelpshiftSupport setMetadataObjectBlock:^(void){
        return [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"name":@"xyz",
                                                                    @"email":@"xyz@abc.com",
                                                                    @"level":gameObject.level,
                                                                    @"score":gameObject.score
                                                                    nil}];
}];

[HelpshiftSupport setMetadataBlock:^(void){
        return [NSDictionary dictionaryWithObjectsAndKeys: @"xyz", @"name",
                                                       @"xyz@abc.com", @"email",
                                                       gameObject.level, @"level",
                                                       gameObject.score, @"score",
                                                       nil];
}];

Please make sure that the objects and keys are NSStrings only. HelpshiftSupportCustomMetadataKey will take preference over setMetadataBlock

Attaching tags with metadata

On tag names & compatibility

  • Applicable to SDK v4.0.0 & above.
  • HSTags must be created in the Helpshift Dashboard (Settings → Tags), otherwise they will be ignored.
  • HSTags must be lowercase since the dashboard automatically converts tags to lowercase. The tags present on the dashboard must exactly match the HSTags.

metadatatags.png

You can attach tags with metadata to every new conversation via a reserved key constant HelpshiftSupportTagsKey to be used with setMetadataBlock: or to pass in withOptions: of support API's (supported from v4.2.0 and above) (of type NSDictionary) to pass NSArray(of only NSStrings) which get intepreted at server and added as Tags for the every new conversation.

If an object in NSArray is not of type NSString then the object will be removed from Tags and will not be added for the new conversation.

HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customMetaData = [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"usertype":@"paid", @"level":@"7", @"score":@"12345"}
                                                                    andTags:@[@"feedback",@"paid user",@"v4.1"]];
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfigs:apiConfig];
HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customMetaData = [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"usertype":@"paid", @"level":@"7", @"score":@"12345"}];
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfigs:apiConfig];

Developers can still use the setMetadataBlock: api to pass tags.

[HelpshiftSupport setMetadataObjectBlock:^(void){
    return [[HelpshiftSupportMetaData alloc] initWithMetaData:@{@"usertype": @"paid",
                                                                @"level":@"7",
                                                                @"score":@"12345"}
                                                      andTags:@[@"feedback",@"paid user",@"v4.1"];
}];

NSDictionary *metaDataWithTags = @{@"usertype": @"paid",
                                   @"level":@"7",
                                   @"score":@"12345",
                                   HelpshiftSupportTagsKey:@[@"feedback",@"paid user",@"v4.1"]};

[HelpshiftSupport showFAQs:self
               withOptions:@{@"gotoConversationAfterContactUs":@"YES",
       HelpshiftSupportCustomMetadataKey: metaDataWithTags}];
NSDictionary *metaData = @{@"usertype": @"paid", @"level":@"7", @"score":@"12345"]};

[HelpshiftSupport showConversation:self
                       withOptions:@{HelpshiftSupportCustomMetadataKey: metaData}];

Developers can still use the setMetadataBlock: api to pass tags.

[HelpshiftSupport setMetadataBlock:^(void){
    return [NSDictionary dictionaryWithObjectsAndKeys:@"xyz", @"name",
           @"xyz@abc.com", @"email",
           [NSArray arrayWithObjects:@"feedback",@"paid user",nil], HelpshiftSupportTagsKey, nil];
}];

Example of using a custom logging mechanism with metadata

Assume you have your own custom logging mechanism for apps that returns a URL (which takes you to your relevant log viewer), and you would want that URL to be sent with each new conversation the user initiates. Say you have a button "Send Feedback" in your application whose touch event is linked to a method sendFeedback: where you want to call Helpshift showConversation: or any other support session.Then you can implement something like:

- (IBAction) sendFeedback:(id) sender {

    // Manage your UI for posting logs and retrieving URLs
    // Post logs and retrieve URL
    Send logs to your custom logs server
    Retrieve log URL from response

    // Set metadata with URL
    [HelpshiftSupport setMetadataBlock:^(void){
        return [NSDictionary dictionaryWithObjectsAndKeys: URL, @"logURL",nil];
    }];

    // Call Helpshift showConversation
    [HelpshiftSupport showConversation:self];
}

Please make sure that the metadata is already present before presenting any support session.

Debug logs

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 HelpshiftSupport's log: API.

+ (void) log:(NSString *)format, ...;

Example usage

- (void) userUpdatedSomeSetting:(NSString *)settingName {
    ...
    [HelpshiftSupport log:@"User updated setting: %@", settingName];
    ...
}

or,

- (void) userVisitedCheckoutPage {
    ...
    [HelpshiftSupport log:@"User went to checkout page"];
    ...    
}

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