Campaigns

Taking customer engagement to the next level with Helpshift SDK

Integration Guide

Automated Integration using Cocoapods

To start using Helpshift v7.6.0 in your project, add one of the following lines to your Podfile according to the version which you wish to integrate.

pod 'Helpshift', '7.6.0-withCampaigns'            # For normal version
pod 'Helpshift', '7.6.0-withCampaigns-bitcode'    # For bitcode version

And run pod install or pod update to refresh your cocoapods dependencies.

You can now move on to Initializing Helpshift in your App.

Manual Integration

Get the latest SDK zip

Download the latest for the Helpshift iOS SDK.

Download SDK v7.6.0-withCampaigns

The zip file contains

HelpshiftSupport.h
Support API header file
HelpshiftCampaigns.h
Campaigns API header file
HelpshiftAll.h
Combined Support + Campaigns API header file
HelpshiftInbox.h
Inbox Data API header file
HelpshiftCore.h
Core API header file
libHelpshift.a
Bitcode incompatible version of the Helpshift library
libHelphsift-bitcode.a
Bitcode compatible version of the Helpshift library
HsUIResourcesBundle
Bundle file containing images and XIB files used by the SDK
HsLocalization
Bundle file containing the default Helpshift translation files.
HSThemes/
Folder containing skinning configuration to match the design of your app
HelpshiftDefaultLocalizations/
Folder containing language translations which can be used to create the HelpshiftCustomLocalization bundle. This is just for reference.
NOTICE.txt/
License information about third-party code.

Add the latest stable SDK release to your project

  • Unzip the SDK & drag-drop the HelpshiftSupport.h, HelpshiftCampaigns.h, HelpshiftCore.h, HelpshiftAll.h, HelpshiftInbox.h header files, libHelpshift.a, HsUIResourceBundle.bundle, HSThemes/ and HsLocalization.bundle files into your Xcode project.
  • In Build Phases, verify that libHelpshift.a is in the Link Binary with Libraries and the Helpshift resources are in Copy Bundle Resources
  • Add the following frameworks to Link Binary with Libraries -

    • CoreGraphics
    • QuartzCore
    • CoreText
    • SystemConfiguration
    • CoreTelephony
    • UIKit
    • libsqlite3.tbd
    • libicucore.tbd (needed only for v6.0.0 or later)
    • libz.tbd
    • Security
    • QuickLook
    • CoreLocation
    • MobileCoreServices
    • CoreSpotlight
    • Photos (needed only for v5.10.0 or later)
    • WebKit (needed only for v5.10.0 or later)
    • FileProvider (needed for v7.0.0 or later)
  • Add -ObjC flag to the Other Linker Flags under Build Settings section.

    Explanation : The Helpshift SDK defines its own categories and uses method swizzling internally to listen to some application delegates required for doing background data syncing. Apple guidelines are still unclear about the usage of method swizzling but we have independently confirmed that usage itself is not grounds for rejection in the app review. They take into account the purpose and scope of the swizzled methods and only reject if the application code appears to use hidden APIs or do some other malicious activity. Which we do not!

Please note that SDK may crash if HsUIResourceBundle.bundle file is not inlcuded in your project or is not updated to the correct version required by your current SDK version.

Add only required theme from HSThemes

HSThemes folder contains two files, HelpshiftConfig.plist and HelpshiftConfigDark.plist. Depending on your app theme, you can just keep one file in the project and remove the other.

CFBundleExectuable errors while submitting the App

Applicable to version 5.5.0

Some customers have reported seeing errors like below when you submit your app with Helpshift to the App store.

ERROR ITMS-90535: "Unexpected CFBundleExecutable Key.
The bundle at 'Example.app/HsUIResourceBundle.bundle' does not contain a bundle executable.
If this bundle intentionally does not contain an executable, consider removing the CFBundleExecutable key from its Info.plist and using a CFBundlePackageType of BNDL.
If this bundle is part of a third-party framework, consider contacting the developer of the framework for an update to address this issue."

To eliminate this error, please follow the below mentioned steps.

  1. Navigate to the HsUIResourceBundle file via the Finder
  2. Open the bundle file by doing Show Package Contents
  3. Open the Info.plist file via an external editor
  4. Find and remove the CFBundleExecutable key and its value string

App crashes after attachment button is tapped

Applicable to version 5.7.0 and above on iOS 10 beta

Add NSPhotoLibraryUsageDescription key in you application info plist file

Add NSPhotoLibraryUsageDescription key in your application info plist file

If your app does not use this permission, you would need to add this key as well as description for the same. Not adding this key-description pair might cause app rejection.

Description text: “We need to access photos library to allow users manually pick images meant to be sent as attachment for help and support reasons.”

Note that this is just a suggested description. If you need localisations for the same, please Contact Us

Please replace all the old files with new files.

Helpshift is now ready to help you have conversations with your users! Head over to Initializing Helpshift in your App.

Integrating with a Swift Project

If you are working in Swift, you can use Helpshift with the mix and match feature. Mix and match works by using an Objective-C bridging header to expose the required Objective-C files to your Swift code.

In case you already have an Objective-C bridging header set up in your project you can skip to Step 2.

Adding an Objective-C bridging header

If your project does not already bridge to Objective-C, you will need to create a bridging file and let Xcode know. Add a new Header file to your project.

This will be your Objective-C bridging header so you can name it something appropriate like ObjC-Bridge.h.

Next, in your project's Build Settings look for Objective-C Bridging Header under Swift Compiler - Code Generation.

Add the path to your bridge file. The path needs to be relative to your project. For example, if the project name is Helpshift-Demo and the bridge is ObjC-Bridge.h, then the path should be: Helpshift-Demo/ObjC-Bridge.h

Add Helpshift to the Objective-C bridging header

Inside your Objective-C bridging header, add these lines:

#import "HelpshiftAll.h"
#import "HelpshiftSupport.h"
#import "HelpshiftCore.h"

You are now ready to start using Helpshift in your Swift code. For example, you can use the initialisation function this way:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    ...
    HelpshiftCore.initialize(with: HelpshiftAll.sharedInstance())
    HelpshiftCore.install(forApiKey: "<YOUR_API_KEY>", domainName: "<YOUR_HELPSHIFT_DOMAIN>", appID: "YOUR_APP_ID")
    ...
    return true
}

Start using Helpshift

Helpshift is now integrated in your app and ready to collect meaningful data about your users.

Initializing Helpshift in your app

Helpshift uniquely identifies each registered App using a combination of 3 tokens:

API Key
Your unique developer API Key
Domain Name
Your Helpshift domain name without any http: or slashes. E.g. happyapps if your account is happyapps.helpshift.com
App ID
Your App's unique ID

You can find these tokens by navigating to Settings>SDK (for Developers) in your agent dashboard. Select your App and the correct platform from the dropdowns and copy the 3 tokens to be passed when initializing Helpshift. show me

Initialize Helpshift by calling the HelpshiftCore's install function:

  1. Initialize the HelpshiftCore with the Helpshift service that you want to use.
  2. Call the HelpshiftCore's install function.
    #import "HelpshiftCore.h"
    ...
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        ...
        [HelpshiftCore initializeWithProvider:[HelpshiftAll sharedInstance]];
        [HelpshiftCore installForApiKey:@"YOUR_API_KEY" domainName:@"YOUR_HELPSHIFT_DOMAIN" appID:@"YOUR_APP_ID"];
        ...
        return YES;
    }

Placing the install call

You should not place the install call anywhere other than application:didFinishLaunchingWithOptions: Placing it elsewhere might cause unexpected runtime problems. From version 5.7.0 and above the Helpshift install call will throw InstallException in case the validation of the SDK keys fail.

Engaging with your Customers

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.

Automatically Collected Data

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.

Device information that the SDK may collect automatically

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

Data Collected from Developer

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.

Data Collection APIs

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:

  • Strings
  • Integers
  • Booleans
  • Date
  • long long [Available from SDK v6.3.0 and above]

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}];

Verify User Properties

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)

User Management APIs

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.

  • To send the login information to the Helpshift SDK, please use the [HelpshiftCore loginWithIdentifier:withName:andEmail] API.
  • If you want to switch users from one to another, you can use the same API with different user credentials.
  • If you allow a user to logout of your app, you can pass on that information to us by using the [HelpshiftCore logout] API. To logout user, do not set a dummy value as user-id.
  • Use login and logout only if you provide valid user-ids and want Helpshift to record it.

If you want to only set the name and email of the current user, you can use the [HelpshiftCore setName:andEmail:] API.

Inbox APIs

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.

showInboxOnViewController

You can use the showInboxOnViewController API to show a list of In-app Campaign messages that have been received by the user.

Definition
showInboxOnViewController:withConfig:
Example Code
[HelpshiftCampaigns showInboxOnViewController:self withConfig:nil]; // where self is the view controller you're calling Helpshift from

Definition
showInboxOnViewController:withOptions:
Example Code
[HelpshiftCampaigns showInboxOnViewController:self withOptions:nil]; // where self is the view controller you're calling Helpshift from

showMessageWithId

You can use the showMessageWithId API to show the Campaign message screen in response to a notification received for the Campaign.

Definition
showMessageWithId:onViewController:withConfig:
Example Code
[HelpshiftCampaigns showMessageWithId:[[notification objectForKey:@"aps"] objectForKey:@"cid"] onViewController:self withConfig:nil]; // where self is the view controller you're calling Helpshift from

Definition
showMessageWithId:onViewController:withOptions:
Example Code
[HelpshiftCampaigns showMessageWithId:[[notification objectForKey:@"aps"] objectForKey:@"cid"] onViewController:self withOptions:nil]; // where self is the view controller you're calling Helpshift from

requestUnreadMessagesCount

If 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

  • Applicable to SDK v6.3.0 & above.
  • Use the following method to set the delegate, where self is the object implementing the delegate. [[HelpshiftCampaigns sharedInstance] setDelegate:self];
  • If you now call the method [HelpshiftCampaigns requestUnreadMessagesCount]; it will return a notification count from server in the didReceiveUnreadMessagesCount:(NSInteger)count delegate method.

refetchMessages

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.

Inbox Data APIs

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.

HelpshiftInbox

The main class which is responsible for providing the Data API is the HelpshiftInbox class.

The main APIs in this class are :

  1. sharedInstance : Return the shared instance object of the HelpshiftInbox class.
  2. cleanUp : clean up any local memory which the HelpshiftInbox class is using.
  3. getAllInboxMessages : Return an NSArray of id objects which represent the active Campaign messages for the current user. This method does not return any expired campaign.
  4. getInboxMessageForId : Return the id object for the given message id. This method returns nil if the message is expired for the given id before calling this method.
  5. markInboxMessageAsRead : 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.
  6. 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.
  7. deleteInboxMessage : Remove the Campaign message from the Helpshift SDK's storage.

HelpshiftInboxMessage

The HelpshiftInboxMessage is a protocol which represents the detailed Campaign message.

The APIs which are available to retrieve information from the message are:

  1. getIdentifier : Get the message identifier.
  2. 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.
  3. getIconImage : Get the UIImage which was set as the icon image of the Campaign.
  4. getTitle : Get the title of the Campaign.
  5. getTitleColor : Get the title color of the Campaign.
  6. getBody : Get the body of the Campaign.
  7. getBodyColor : Get the color of the body of the Campaign.
  8. getBackgroundColor : Get the background color of the Campaign.
  9. getReadStatus : Get the read status of the Campaign.
  10. getSeenStatus: Get the seen status of the Campaign.
  11. getCreatedAt : Get the created-at timestamp of the Campaign.
  12. 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.

  13. getCountOfActions : Get the count of actions that were added to the Campaign.

  14. getActionTitleAtIndex : Get the title of the action button at specified index.
  15. getActionTitleColorAtIndex : Get the color of the action button at specified index.
  16. getActionGoalCompletionAtIndex : Get whether the action at specified index counts as goal completed for this Campaign.
  17. executeActionAtIndex:onViewController: : Execute the action that was configured for the button at specified index.
  18. 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'.)
  19. getActionDataAtIndex : Get the action data of the button at the given index. (It will be null if the action type doesn't require data.)

HelpshiftInboxDelegate

If you want to get delegate callbacks in response to updates to the Campaigns data in the Helpshift SDK, please set the delegate property of the HelpshiftInbox object.

Starting version 7.5.0, the inboxDelegate property of the HelpshiftCampaigns class is deprecated. Please use this delegate instead.

For example :

[HelpshiftInbox sharedInstance].delegate = self;

The methods which are part of the HelpshiftInboxDelegate are :

Compulsary methods :

  1. inboxMessageAdded:(id<HelpshiftInboxMessage>)newMessage : Called when a new Campaign message is received.
  2. inboxMessageDeleted:(NSString *)identifier : Called when a Campaign message gets deleted.

Optional methods :

  1. failedToAddInboxMessageWithId:(NSString *)identifier : Called when a Campaign message does not get added to the Helpshift DB.
  2. iconImageDownloadedForInboxMessage:(NSString *)identifier : Called when download completes for a Campaign icon image.
  3. coverImageDownloadedForInboxMessage:(NSString *)identifier : Called when download completes for Campaign cover image.
  4. inboxMessageMarkedAsSeen:(NSString *)identifier : Called when a campaign is seen by the user.
  5. inboxMessageMarkedAsRead:(NSString *)identifier : Called when a campaign is marked as read by the user.

HelpshiftInboxNotificationDelegate

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;

Configuring Campaigns

enableInboxPolling

This change controls whether or not the application should poll for Campaign messages in addition to relying on push notifications. If your application does not use this option, the SDK will use both push notifications and polling to receive Campaign messages. If you want to use only push notifications for Campaigns, set this option to NO.

Option:
enableInboxPolling
Values:
YES / NO
Default:
YES
Min SDK
v5.8.0
Supported by:
installForApiKey:domainName:appID:

Example:

    HelpshiftInstallConfigBuilder *installConfigBuilder = [[HelpshiftInstallConfigBuilder alloc] init];
    installConfigBuilder.enableInboxPolling = YES;
    HelpshiftInstallConfig *installConfig = [installConfigBuilder build];
    [HelpshiftCore initializeWithProvider:[HelpshiftAll sharedInstance]];
    [HelpshiftCore installForApiKey:@"YOUR_API_KEY" domainName:@"YOUR_DOMAIN_NAME" appID:@"YOUR_APP_ID" withConfig:installConfig];

Option:
enableInboxPolling
Values:
@"YES" / @"NO"
Default:
@"NO"
Min SDK
v5.5.0
Supported by:
installForApiKey:domainName:appID:

Example:

    [HelpshiftCore initializeWithProvider:[HelpshiftAll sharedInstance]];
    NSDictionary *installConfig = @{ @"enableInboxPolling" : @"yes"};

    [HelpshiftCore installForApiKey:@"" domainName:@"" appID:@"" withOptions:installConfig];

Helpshift Campaigns Delegates

You have to define a class which implements Helpshift Campaigns Delegates and then pass this to Helpshift using [[HelpshiftCampaigns sharedInstance] setDelegate:delegate]; method.

For example:

Class Definition:

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

@interface MyDelegates : NSObject <HelpshiftCampaignsDelegate>
@end

Class Implementation

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

@implementation MyDelegates {

}

- (void) didReceiveUnreadMessagesCount:(NSInteger)count {
    // your code here
}

- (void) helpshiftCampaignsSessionHasBegun {
    // your code here
}

- (void) helpshiftCampaignsSessionHasEnded {
    // your code here
}

Campaigns Session started

To keep track of when a Campaigns session starts in your app, implement this delegate callback. This delegate will get fired every time the Campaigns session starts.

- (void) helpshiftCampaignsSessionHasStarted {
  // your code here.
}

Campaigns Session ended

To keep track of when the Campaigns session ends, implement this delegate callback. This delegate will get fired every time the Campaigns session ends.

- (void) helpshiftCampaignsSessionHasEnded {
  // your code here.
}

Campaigns delegates won't be fired for helpshift support session. To implement support delegates refer support session delegates.

Guidelines

There are some guidelines which app developers need to follow to best use the Campaigns feature.

Limit on custom user properties

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.

Allowed values for custom user properties

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

  1. "level"
  2. "user-category"
  3. "is_pro"

Examples of invalid keys

  1. "$-spent"
  2. "-level-"

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.

  • Notification badge count on application icon wont include the count of unread messages from campaigns inbox.