Helpshift SDK X for iOS

Helpshift Delegates

The Helpshift SDK provides delegate callbacks to help app developers track a user's activities within the help section.

All the public APIs in the SDK should be called after initializing the SDK via Helpshift installWithPlatformId API

Helpshift Support Delegates implementation

You have to define a class which implements Helpshift Support Delegates and then pass this to Helpshift by setting the delegate property of the sharedInstance.

Example

#import <Foundation/Foundation.h>
@import HelpshiftX;

@interface MyDelegates : NSObject <HelpshiftDelegate>
@end

Class Implementation

#import <Foundation/Foundation.h>
#import "MyDelegates.h"

@implementation MyDelegates {

}

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    // your code here
}

- (void) authenticationFailedForUserWithReason:(HelpshiftAuthenticationFailureReason)reason {
    // your code here
}

@end

Class Usage:

@property (strong, nonatomic) MyDelegate *delegate;
.
.
.
.
delegate = [[MyDelegates alloc] init];
Helpshift.sharedInstance.delegate = self;


import Foundation
import HelpshiftX

class HelpshiftDelegateHandler: HelpshiftDelegate {
    func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        // Your code here
    }

    func authenticationFailedForUser(with reason: HelpshiftAuthenticationFailureReason) {
        // Your code here
    }
}

Class Usage:

var delegateHandler: HelpshiftDelegateHandler
.
.
.
.
delegateHandler = HelpshiftDelegateHandler()
Helpshift.sharedInstance().delegate =  delegateHandler

Please make sure you set the delegate before calling the Conversation API so that they can callback your delegate methods.

Helpshift Events

Helpshift session started event

This event gets fired when the Helpshift session starts

Event name: HelpshiftEventNameSessionStarted
Event data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameSessionStarted]) {
        NSLog(@"Helpshift session started.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        if eventName == HelpshiftEventNameSessionStarted {
            print("Helpshift session started.")
        }
}

Helpshift session ended event

This event gets fired when you call the Helpshift session ends

Event name: HelpshiftEventNameSessionEnded
Event data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameSessionEnded]) {
        NSLog(@"Helpshift session ended.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        if eventName == HelpshiftEventNameSessionEnded {
            print("Helpshift session ended.")
        }
}

Unread Message Count Event

This event gets fired when you call [Helpshift requestUnreadMesssageCount:]; to request unread messages count.

Event name: HelpshiftEventDataUnreadMessageCount
Event data: HelpshiftEventDataUnreadMessageCount
Event data: HelpshiftEventDataUnreadMessageCountIsFromCache

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameReceivedUnreadMessageCount]) {
        int count = data[HelpshiftEventDataUnreadMessageCount];
        NSLog(@"Unread count: %d", data[HelpshiftEventDataUnreadMessageCount]);
        NSLog(@"Is unreadCount served from local cache : %d", data[HelpshiftEventDataUnreadMessageCountIsFromCache]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameReceivedUnreadMessageCount {
        guard let data = data else { return }
        let count = data[HelpshiftEventDataUnreadMessageCount] as? Int
        let isFromCache = data[HelpshiftEventDataUnreadMessageCount] as? Bool
        print("Count: \(count), fromCache: \(isFromCache)")
    }
}

  • If you now call the method [Helpshift requestUnreadMessageCount:YES]; it will return a notification count from server in the above delegate method. The notification count here can be fetched either from the cache or from the Helpshift servers, the count from Helpshift’s servers is rate limited and it returns the value only if a subsequent call is made to the API, after the reset timeout or when the user just closes the chat screen (whichever is earlier). For an active issue, the reset timeout is 1 minute and 5 minutes for inactive issues.

  • If you want to retrieve the current notification count stored locally, you can call the same method with the parameter set to false, [Helpshift requestUnreadMessageCount:NO];. In this case, SDK returns the count of unread messages available locally in this delegate method.

  • Locally saved unread message count are useful for saving an additional network call.

Conversation Status Event

This event contains information about the current ongoing conversation.

Event name: HelpshiftEventNameConversationStatus
Event Data: HelpshiftEventDataLatestIssueId
Event Data: HelpshiftEventDataLatestIssuePublishId
Event Data: HelpshiftEventDataIsIssueOpen

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationStatus]) {
        NSLog(@"Issue ID: %@", data[HelpshiftEventDataLatestIssueId]);
        NSLog(@"Publish ID: %@", data[HelpshiftEventDataLatestIssuePublishId]);
        NSLog(@"Is issue open: %@", data[HelpshiftEventDataIsIssueOpen]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationStatus {
        guard let data = data else { return }
        let issueId = data[HelpshiftEventDataLatestIssueId]
        let publishId = data[HelpshiftEventDataLatestIssuePublishId]
        let issueOpen = data[HelpshiftEventDataIsIssueOpen]

        print("Issue id \(issueId), publishId: \(publishId), issueOpen: \(issueOpen)")
    }
}

Widget Toggle Event

This event is triggered when the user opens or exits the chat screen.

Event name: HelpshiftEventNameWidgetToggle
Event Data: HelpshiftEventDataVisible

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameWidgetToggle]) {
        NSLog(@"Is chat screen visible: %@", data[HelpshiftEventDataVisible]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameWidgetToggle {
        guard let data = data else { return }    
        let widgetStatus = data[HelpshiftEventDataVisible]
        print("Is chat screen visible: \(widgetStatus)")
    }
}

Message Add Event

This event is triggered when the user adds a message in a conversation. It might be a text message, response via bot input, or an attachment. The event data object has type and body keys, which indicates the type and body of the message added by the user.

Event name: HelpshiftEventNameMessageAdd
Event Data: HelpshiftEventDataMessageType
Event Data: HelpshiftEventDataMessageTypeText
Event Data: HelpshiftEventDataMessageTypeAttachment
Event Data: HelpshiftEventDataMessageBody

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameMessageAdd]) {
        NSLog(@"New message added with body: %@", data[HelpshiftEventDataMessageBody]);
        NSLog(@"New message added with type: %@", data[HelpshiftEventDataMessageType]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameMessageAdd {
        guard let data = data else { return }    
        let messageBody = data[HelpshiftEventDataMessageBody]
        let messageType = data[HelpshiftEventDataMessageType]
        print("Message: \(messageBody), type: \(messageType)")
    }
}

Conversation Start Event

This event triggers when the user sends the first message in a conversation. The event data object has a key, message, which includes the message string the end-user sent to start the conversation.

Event name: HelpshiftEventNameConversationStart
Event Data: HelpshiftEventDataMessage

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationStart]) {
        NSLog(@"Conversation started with text: %@", data[HelpshiftEventDataMessage]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationStart {
        guard let data = data else { return }    
        let messageBody = data[HelpshiftEventDataMessage]
        print("Conversation started with text: \(messageBody))")
    }
}

CSAT Submit Event

This event is triggered when the user submits a CSAT rating after the conversation ends. The event data object has rating and additionalFeedback keys, which indicates the (star) rating and the additional comments provided by the user with the CSAT form.

Event name: HelpshiftEventNameCSATSubmit
Event Data: HelpshiftEventDataRating
Event Data: HelpshiftEventDataAdditionalFeedback

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameCSATSubmit]) {
        NSLog(@"CSAT Submitted with rating: %@", data[HelpshiftEventDataRating]);
        NSLog(@"CSAT Submitted with feedback: %@", data[HelpshiftEventDataAdditionalFeedback]);
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameCSATSubmit {
        guard let data = data else { return }    
        let rating = data[HelpshiftEventDataRating]
        let feedback = daat[HelpshiftEventDataAdditionalFeedback]
        print("CSAT Rating: \(rating), feedback:\(feedback))")
    }
}

Conversation End Event

This event is triggered when the conversation ends (resolved or rejected) and it cannot be reopened.

Event name: HelpshiftEventNameConversationEnd
Event Data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationEnd]) {
        NSLog(@"Conversation ended.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationEnd {
        print("Conversation ended")
    }
}

Conversation Rejected Event

This event is triggered when an agent rejects the conversation.

Event name: HelpshiftEventNameConversationRejected
Event Data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationRejected]) {
        NSLog(@"Conversation rejected.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationRejected {
        print("Conversation rejected")
    }
}

Conversation Resolved Event

This event is triggered when an agent resolves the conversation.

Event name: HelpshiftEventNameConversationResolved
Event Data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationResolved]) {
        NSLog(@"Conversation resolved.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationResolved {
        print("Conversation resolved")
    }
}

Conversation Reopened Event

When resolution question is enabled, the users are asked if they're satisfied with the resolution. If the user rejects it and sends a new message, then the conversation is reopened and the Conversation Reopened event is triggered.

Event name: HelpshiftEventNameConversationReopened
Event Data: nil

Example: 

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationReopened]) {
        NSLog(@"Conversation reopened.");
    }
}


func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationReopened {
        print("Conversation reopened")
    }
}

Authentication failure delegate

If identity verification fails, the SDK will invoke one of the following delegates to notify the application of the failure:

Delegate When it is called How to use
- (void) authenticationFailedForUserWithReason:(AuthenticationFailureReason) AuthTokenNotProvided When no 'user authentication token' is provided If you do not plan on sending an 'user authentication token' but plan on implementing it in the future, you can use this failure delegate to show your own alerts to the userm such as a prompt to update the app. You may want to use this if you are using the login API without the 'user authentication token', as these users will be considered unverified once Identity Verification is enabled on the Dashboard. Using this delegate is completely optional - Helpshift will prevent unverified users from being able to file Issues, as mentioned previously.
- (void) authenticationFailedForUserWithReason:(AuthenticationFailureReason)InvalidAuthToken
  • When the 'user authentication token' is invalid
 If the HMAC Digest being provided via LoginAPI is invalid, Helpshift will prevent the users from filing Issues. The 'user authentication token' can be invalid if:
  • You made a programming error. View
  • You regenerated the secret key on the Dashboard, but didn't update the 'user authentication token'.
  • A 3rd party is trying to make requests.
  • When the 'user authentication token' is invalid, end users are not able to file Issues and an error is shown to them, as mentioned previously. You can use this delegate if you want to show your own alerts or re-fetch the correct auth token from your server.
Copyright © 2023 Helpshift Inc.
Call Us: (888) 983-2664