iOS SDK

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, login into your HelpCrunch account, then go to the Settings pageSet up & CustomizeiOS APPs and press “Add new”. Fill the iOS App Name field and press “Apply” button:
iOS Apps

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"
    withAttributes:@{
    HC_ApplicationIdAttributeName:@"YOUR_APP_ID",
    HC_ApplicationSecretAttributeName:@"YOUR_APP_SECRET"
    }];
    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]
  9. After you have called the method it will look like this:
    iOS App

3. Enable Push Notifications (optional)

We believe that push notifications are 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"
withAttributes:@{
HC_ApplicationIdAttributeName:@"YOUR_APP_ID",
HC_ApplicationSecretAttributeName:@"YOUR_APP_SECRET"
}];
[HelpCrunch registerForRemoteNotifications];
if (![HelpCrunch didReceiveRemoteNotificationWithLaunchOptions:launchOptions]) {
// this push notification does not belong to HelpCrunch
}
...
return YES;
}

If the registration is successful, the callback method
-application:didRegisterForRemoteNotificationsWithDeviceToken:
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].
Be sure to put a unique User ID string in withUserID method for all your users. Constructing empty users with no data will not work (you can have no use of an empty user you cannot identify after all).

NSDictionary *user = @{
HC_UserNameAttributeName:@"Username",
HC_UserEmailAttributeName:@"Email",
HC_UserIdAttributeName:@"UserId"
};
[HelpCrunch updateUser:user];

You can also pass a user data when initializing HelpCrunch in your application:

[HelpCrunch initForOrganization:@"YOUR_HELPCRUNCH_SUBDOMAIN"
withAttributes:@{
HC_ApplicationIdAttributeName:@"YOUR_APP_ID",
HC_ApplicationSecretAttributeName:@"YOUR_APP_SECRET",
HC_UserAttributeName: user
}];

After you have added user’s data and called [HelpCrunch updateUser:user]; it’s data will appear in your HelpCrunch admin account in chat with that user:
Sent User data in chat

In addition to user’s name / email / and ID HelpCrunch lets you send additional attributes of your customers in custom data. You can do it with [HelpCrunch updateUserData:userData]. With the custom data you can send any information about users you wish to track. Custom data is key/value pairs and can contain numbers, strings or boolean data. This feature will only work if you have your user have a HC_UserIdAttributeName:

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

Custom data parameters will appear in chat with user at your HelpCrunch admin account just as same as main user attributes (name, email, user id):
Custom data in chat

Also you will be able to search through your users by custom data you at the “Contacts” page. There 3 types of custom data you can search by: integers, strings and boolean:
Custom data search

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. Localization

To be able to localize your chat in your application or change it’s texts you need to:

  1. Create a “localizable.string” and select desirable localization:

  2. Then add string resources to Localizable.string file with needed texts. In HelpCrunch SDK you can use these names:

    "helpcrunch.chat.title" = "Help & Feedback";
    "helpcrunch.chat.welcome-message" = "Your suggestions, ideas or complaints greatly help us. We'll get back to you pretty soon!";
    "helpcrunch.chat.button.send" = "Send";
    "helpcrunch.alert.title" = "Help & Feedback";
    "helpcrunch.alert.button.cancel" = "Cancel";
    "helpcrunch.alert.button.reply" = "Reply";
    "helpcrunch.alert.button.ok" = "OK";
    "helpcrunch.connection.alert.error" = "Connection Error";
    "helpcrunch.connection.no-internet-connection.alert.title" = "No Internet Connection";
    "helpcrunch.connection.no-internet-connection.alert.text" = "Message will be sent once connection restored";
    "helpcrunch.connection.unknown-error" = "Unknown server error";
    "helpcrunch.profile.title" = "Profile";
    "helpcrunch.profile.enter-your-name" = "Enter your name";