This tutorial provides you with a step-by-step guide to configuring your iOS SDK in your mobile application.

We will start on configuring your app in your HelpCrunch profile, then proceed to implementing and configuring HelpCrunch SDK in your iOS project, and finally, we’ll describe how to create a push-enabled iOS application and send notifications to users.

1. Configuring app on your HelpCrunch profile

Download HelpCrunch SDK

You will find it either on the Settings page when logged into your HelpCrunch account, or you can download it here.

Download SDK

Create a new app

To add a new app, open Settings page in your HelpCrunch account and press “Add application”.

Add APNS certificate

If you plan to use push notifications to inform your application users about new messages from HelpCrunch, you will need to add APNS certificate and APNS certificate passpharse to the app. Skip this step if you do not plan to use push notifications. More details about push notification integration can be found in Enabling Push Notifications section

2. Adding SDK to your project

  1. Drag the HelpCrunch SDK (HelpCrunchSDK.framework, HelpCrunchSDK.bundle) into your project’s file folder
  2. Add JavaScriptCore.framework, SystemConfiguration.framework, AudioToolbox.framework to the project
  3. Add “-ObjC” option to “Other Linker Flags” in project settings
  4. Add the following import to the top of the AppDelegate.m:

    #import "HelpCrunch.h"
  5. Initialize the Helpcrunch SDK in HelpCrunch.h file:

    [HelpCrunch initForOrganization:@"YOUR_HELPCRUNCH_SUBDOMAIN"
    You can copy this code on apps list in your HelpCrunch account
  6. By default HelpCrunch SDK is initialized on the app startup, so that you can always get the latest data about your users. We also recommend to implement the method [HelpCrunch restoreFromBackground]; in application WillEnterForeground to initialize the HelpCrunch SDK when the app is restored from background.
  7. To show the HelpCrunch UI simply call the showFromController helper method on HelpCrunch:

    [HelpCrunch showFromController:viewController];
    controller – required – the controller to be presented from.
  8. You can check if chat is currently displayed using:

    [HelpCrunch isShowing]

3. Enable Push Notifications (optional)

We believe that push notifications is a great way to add real-time messaging to your application and inform your app users that there is a new message came from HelpCrunch server (i.e. from your admin dashboard). It allows you to stay in touch with your users even when the application is not in the foreground. Although, HelpCrunch Mobile SDK does not necessary require the implementation of push notifications and end users of your application will still be able to receive messages, but in this case, the end users will discover that new messages arrived only after opening HelpCrunch page.

When implementing push notifications in your app, you should remember that push notifications are not available in the iOS Simulator. To start developing this featured you will need an iOS device, as well as an Apple Developer license.

Add Code for a Push Enabled iOS Applications

To register the current device for push add the following code in the app delegate’s
-application:didFinishLaunchingWithOptions: method:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[HelpCrunch initForOrganization:@"YOUR_HELPCRUNCH_SUBDOMAIN"
[HelpCrunch registerForRemoteNotifications];
if (![HelpCrunch didReceiveRemoteNotificationWithLaunchOptions:launchOptions]) {
// this push notification does not belong to HelpCrunch
return YES;

If the registration is successful, the callback method
in the application delegate will be executed. We will need to implement this method and use it to inform HelpCrunch about this new device.

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
[HelpCrunch setDeviceToken:deviceToken];

When a push notification is received while the application is in the background, it is displayed in the iOS Notification Center. However, if the notification is received while the app is active, it is up to you how to handle it. To do so, we can implement the [application:didReceiveRemoteNotification] method in the app delegate. In our case, we will simply ask HelpCrunch to handle it for us. HelpCrunch will create a modal alert and display the push notification’s content.

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
if (![HelpCrunch didReceiveRemoteNotification:userInfo]) {
// this push notification does not belong to HelpCrunch

You can disable a default alert and implement your own alert. For disabling a default alert:

[HelpCrunch useDefaultAlertForRemoteNotification:NO]; // Defaults to YES

4. App Users

By default HelpCrunch SDK requires a user to enter his name before sending messages. You can disable this with following code:

[HelpCrunch customerNameRequired:NO]; // Defaults to YES

Saving app user data to HelpCrunch is done by calling [HelpCrunch updateUser:user]

NSDictionary *user = @{HC_UserNameAttributeName:@"Username",
[HelpCrunch updateUser:user];

HelpCrunch lets you send custom attributes about your customers using
[HelpCrunch updateUserData:userData]

The custom attributes allow to send any information you wish to track about users. Send key/value pairs containing any data about users and setup displaying and filters in HelpCrunch admin panel settings.

NSDictionary *userData = @{@"money_spent":@(250),
[HelpCrunch updateUserData:userData];

5. Messages

In order to display the number of new messages in your application, fetch unread messages from the server. Use once after initializing HelpCrunch SDK:

[HelpCrunch checkUnreadMessages:^(NSUInteger numberOfUnreadMessages) {
// show a badge somewhere in your application

Initiate every time you want to display the number on unread messages on UI using the following method:

NSUInteger numberOfUnreadMessages = [HelpCrunch numberOfUnreadMessages];

6. User authentication mode

Read more about user authentication mode.

We initiate user authentication mode, once you send the following:

During initialization process

NSDictionary *user = @{HC_UserNameAttributeName:@"USER_NAME",
[HelpCrunch initForOrganization:@"YOUR_HELPCRUNCH_SUBDOMAIN"
HC_UserAttributeName: user}];

Or invoke ‘updateUser’ on SDK

[HelpCrunch updateUser:user];

To change user or logout:

[HelpCrunch logout];