Taking customer engagement to the next level with Helpshift SDK
As app developers, one of the most important aspect of making your app awesome is to constantly engage with your customers. To do this, developers need to understand their customers intricately. And this understanding will always come from data. The more data you have about your user's behaviour, the better you can engage with him.
The Helpshift SDK will automatically collect information about a user's device. Any data will only be collected if the app has the required permissions. User engagement data like first usage, last seen, total engagement etc will also be collected automatically by the SDK.
Description |
---|
Device model |
Operating system |
Language code (ISO-639-1) |
Country code (ISO-3166-1 Alpha-2) |
Development platform ?{"ios", "android", "phonegap", "unity"} |
Native Platform ?{"ios", "android"} |
Mobile Carrier |
Push Opt-In |
Push token |
IP address |
Timezone |
App Version |
Helpshift Platform ID |
Helpshift Domain |
Geo Location in Lat, Long |
There is a vast amount of data which app developers already have about an app's user. Meta-data like, what level he is currently on in a game, how much has he spent in the app, what are his preferred brands. The list can be endless. The Helpshift SDK also provides APIs for the developer to send such information to our backend. This information can be further used to create segments of users who can be targeted with an effective campaign.
To start collecting rich meta-data about your user, use the [HelpshiftCampaigns addProperty:with*:]
APIs.
These APIs return the status of adding the property to the collected data. If either the key or the value is
invalid, the API will return false
, true
otherwise.
The HelpshiftCampaigns
class supports these data types:
For example:
[HelpshiftCampaigns addProperty:@"level" withInteger:7]; [HelpshiftCampaigns addProperty:@"user-category" withString:"pro"]; [HelpshiftCampaigns addProperty:@"is-paid" withBoolean:NO]; [HelpshiftCampaigns addProperty:@"last-ride" withDate:[NSDate date]]; [HelpshiftCampaigns addProperty:@"coins" withLongLong:9223372036854775807];
If you want to add multiple properties together, you can use the [HelpshiftCampaigns addProperties:]
API which takes a dictionary which represents the user meta-data in terms property-value pairs.
[HelpshiftCampaigns addProperties:@{@"level" : @7}];
Make sure to configure User Properties correctly so your team can configure segments properly with your user data. The default value of a User Property is a String value, but not all values you are passing through should be Strings.
For example:
Level = 10 should be an Integer, not a String
City = San Francisco should be a String
Other examples of correctly using User Properties:
UserID = 3493849 (Integer)
Plan Type = Enterprise (String)
Registered = false (Boolean)
Last Purchase Date = February 2, 2015 (NSDate)
If your app allows users to log in to their accounts, you can pass along that login information to the Helpshift SDK. This will help us better identify each user. This can be further extended if your app supports multiple users too.
[HelpshiftCore loginWithIdentifier:withName:andEmail]
API.[HelpshiftCore logout]
API. To logout user, do not set a dummy value as user-id. If you want to only set the name
and email
of the current user, you can use the [HelpshiftCore setName:andEmail:]
API.
Starting from version 5.5.0
the Helpshift SDK now supports rich in-app Campaign messages. These messages can contain detailed text and cover images along with customized Action buttons
.
All of these messages are collated in an Inbox
which is provided by the Helpshift SDK out of the box. To enable the user to access his Inbox
, please use the
showInboxOnViewController
API.
You can use the showInboxOnViewController
API to show a list of In-app Campaign messages that have been received by the user.
showInboxOnViewController:withConfig:
[HelpshiftCampaigns showInboxOnViewController:self withConfig:nil];
// where self is the view controller you're calling Helpshift fromshowInboxOnViewController:withOptions:
[HelpshiftCampaigns showInboxOnViewController:self withOptions:nil];
// where self is the view controller you're calling Helpshift fromYou can use the showMessageWithId
API to show the Campaign message screen in response to
a notification received for the Campaign.
showMessageWithId:onViewController:withConfig:
[HelpshiftCampaigns showMessageWithId:[[notification objectForKey:@"aps"] objectForKey:@"cid"] onViewController:self withConfig:nil];
// where self is the view controller you're calling Helpshift fromshowMessageWithId:onViewController:withOptions:
[HelpshiftCampaigns showMessageWithId:[[notification objectForKey:@"aps"] objectForKey:@"cid"] onViewController:self withOptions:nil];
// where self is the view controller you're calling Helpshift fromIf you want to show your user notifications for unread campaign messages, you can use unread message counts provided by Helpshift SDK and display it as a badge. You can get notification counts asynchronously by implementing the HelpshiftCampaignsDelegate in your respective .h and .m files. The badges can be displayed anywhere in your app's interface to tell the user that they have unread campaign messages from you. For example to display a badge on a view (lets say its called yourView which can set its textLabel)
[HelpshiftCampaigns requestUnreadMessagesCount];
You can implement something like the following in the notification count delegate method:
- (void) didReceiveUnreadMessagesCount:(NSInteger)count { dispatch_async(dispatch_get_main_queue(), ^{ yourView.label.text = [NSString stringWithFormat:@"%d",count]; }); }
Similarly for a UITabBarItem in the notification count delegate method you can implement something like:
- (void) didReceiveUnreadMessagesCount:(NSInteger)count { dispatch_async(dispatch_get_main_queue(), ^{ tabBarItem.badgeValue = [NSString stringWithFormat:@"%d",count]; }); }
These will update your view or UITabBarItem whenever a new notification arrives in the delegate method. The situation can vary depending upon your app UI. Showing notification counts at appropriate places would help you draw in your users so that you can engage them more with your campaign.
Delegates and Notification Count
If you want to force a resync of Campaign messages for the current user, you can use the refetchMessages
API. Please note that this function will lead to a network
call being started on a background thread.
The Helpshift SDK presents a standard iOS like UI with the showInbox
API. If your application is styled completely separately and you want to create your custom UI for the list
of Campaign messages, the Helpshift SDK provides a set of APIs to power your UI based on the data that the SDK receives.
The main class which is responsible for providing the Data API is the HelpshiftInbox
class.
The main APIs in this class are :
sharedInstance
: Return the shared instance object of the HelpshiftInbox class.cleanUp
: clean up any local memory which the HelpshiftInbox class is using.getAllInboxMessages
: Return an NSArray of idgetInboxMessageForId
: Return the idmarkInboxMessageAsRead
: Mark the Campaign message as read by the user. This call should be used in cases where the user marks the message as read without first reading the message details.
Please note that this only updates the state of the object in the DB. Any UI updates
that you want to make will need to be handled by the Application. This method will have no effect if called on an expired message.markInboxMessageAsSeen
: Mark the Campaign message as seen by the user. This call should be used in cases where the user reads the message details.
Please note that this only updates the state of the object in the DB. Any UI updates
that you want to make will need to be handled by the Application. This method will have no effect if called on an expired message.deleteInboxMessage
: Remove the Campaign message from the Helpshift SDK's storage.The HelpshiftInboxMessage
is a protocol which represents the detailed Campaign message.
The APIs which are available to retrieve information from the message are:
getIdentifier
: Get the message identifier.getCoverImage
: Get the UIImage which was set as the cover image of the Campaign. This will return nil for the first time when cover image is not downloaded and will start downloading the image. If the cover image got downloaded, it will start returning the appropriate Bitmap object. To know when the cover image gets downloaded, you need to implement the coverImageDownloaded delegate method.getIconImage
: Get the UIImage which was set as the icon image of the Campaign.getTitle
: Get the title of the Campaign.getTitleColor
: Get the title color of the Campaign.getBody
: Get the body of the Campaign.getBodyColor
: Get the color of the body of the Campaign.getBackgroundColor
: Get the background color of the Campaign.getReadStatus
: Get the read status of the Campaign.getSeenStatus
: Get the seen status of the Campaign.getCreatedAt
: Get the created-at timestamp of the Campaign.getExpiryTimeStamp
: Get the expiry timestamp of the Campaign in seconds from 1st January, 1970.
If administrators configure campaigns with a specific expiry time, campaign messages will not be shown after the specified expiry time.
In case the Campaign has no expiry timeStamp specified, then a constant named HS_NO_EXPIRY_TIMESTAMP
is returned.
This feature is available for version 5.9.0 and above.
getCountOfActions
: Get the count of actions that were added to the Campaign.
getActionTitleAtIndex
: Get the title of the action button at specified index.getActionTitleColorAtIndex
: Get the color of the action button at specified index.getActionGoalCompletionAtIndex
: Get whether the action at specified index counts as goal completed for this Campaign.executeActionAtIndex:onViewController:
: Execute the action that was configured for the button at specified index.getActionTypeAtIndex
: Get the action type of button at the given index. This method returns a HelpshiftInboxMessageActionType enum. (If an invalid index is passed, it will return 'Unknown'.)getActionDataAtIndex
: Get the action data of the button at the given index. (It will be null if the action type doesn't require data.)If you want to get delegate callbacks in response to updates to the Campaigns data in the Helpshift SDK, please set the delegate
property or the inboxDelegate
property of the
HelpshiftInbox
or the HelpshiftCampaigns
objects respectively.
For example :
[HelpshiftCampaigns sharedInstance].inboxDelegate = self; // or [HelpshiftInbox sharedInstance].inboxDelegate = self;
The methods which are part of the HelpshiftInboxDelegate
are :
Compulsary methods :
inboxMessageAdded:(id<HelpshiftInboxMessage>)newMessage
: Called when a new Campaign message is received.inboxMessageDeleted:(NSString *)identifier
: Called when a Campaign message gets deleted.Optional methods :
failedToAddInboxMessageWithId:(NSString *)identifier
: Called when a Campaign message does not get added to the Helpshift DB.iconImageDownloadedForInboxMessage:(NSString *)identifier
: Called when download completes for a Campaign icon image.coverImageDownloadedForInboxMessage:(NSString *)identifier
: Called when download completes for Campaign cover image.inboxMessageMarkedAsSeen:(NSString *)identifier
: Called when a campaign is seen by the user.inboxMessageMarkedAsRead:(NSString *)identifier
: Called when a campaign is marked as read by the user.If you want to intercept the push notifications received for a Campaigns inbox message, please set the hsInboxNotificationDelegate
property of the HelpshiftInbox class and override the handleNotificationForInboxMessage:
function in the
HelpshiftInboxNotificationDelegate
protocol. In response to this delegate call, you can either show your own custom UI for the campaign message screen or you can
use the [HelpshiftCampaigns showMessageWithId:onViewController:withOptions]
API.
For example :
[HelpshiftInbox sharedInstance].hsInboxNotificationDelegate = self;
There are some guidelines which app developers need to follow to best use the Campaigns feature.
Currently there is a limit to the number of custom user properties which a developer can register for a given app.
Changes to the same property's value do not count as another property. This limitation applies to the unique keys which can be set.
The limit is 50
including the name and email properties if they are set for a given user.
The keys used for custom properties are restricted to having only alphanumeric characters. The only special characters allowed are "-" and "_", and those also need to be surrounded by alphanumeric characters. Please note that any unicode character is valid.
Examples of valid keys
Examples of invalid keys
For iOS 9 and above, developers need to whitelist the URL Schemes which their App will query.
You must whitelist any URL Schemes that your App wants
to query in your Info.plist
file under the LSApplicationQueriesSchemes
key:
This will Also impact the apps the apps which are not built with the iOS 9 SDK.