Thousands of businesses rely on Hipmob to keep their customers happy. See some here.

Hipmob For iPhone & iPad


Overview

Hipmob provides cloud-hosted live chat for iPhone & iPad (and Android) apps. You get an app key, integrate the Hipmob library into your app, and then you can chat with your users in real time to solve their problems and make them happy. No server setup, no extra steps or code to write, wherever the users are, you get to focus on what you do well. This document covers integrating the Hipmob experience into your iOS app.

15-minute integration on iPhone

To dive right into using Hipmob, take a look at the Hipmob iOS experience sample on Github. This is a fully functional Xcode project that integrates the Hipmob iOS framework. Clone the repository, open the project and explore the various classes to see how to use the Hipmob SDK to open a chat. You can stick your own Hipmob application ID in, then launch it in the debugger and start chatting away!
Full documentation for the Hipmob framework can be seen here. To integrate Hipmob into your own project, read on.
  1. Add a new app in your Hipmob account. Once this is done, we'll generate a Hipmob application ID for your app. Remember this - you'll be using it shortly.
  2. In the Link Binary with Libraries section of your project's Build Phases you'll need to add the following Framework Dependencies:
    • CoreData.framework
    • Security.framework
    • libicucore.dylib
    • CFNetwork.framework
    • UIKit.framework
    • Foundation.framework
    • CoreGraphics.framework
    • CoreTelephony.framework
  3. Download the Hipmob iOS Framework . This includes all the dependencies required (see the Framework Options section for more details).
    Note The Hipmob iOS framework currently only supports iOS 4.3 or higher (the armv7/armv7s architectures). We provide a universal library with support for running the Hipmob code in the simulator as well.
  4. Expand the downloaded archive, and then copy the Hipmob framework folder into your project by dragging the hipmob.framework directory into your Xcode project. Make sure you select the "Copy items into destination group's folder (if needed)" option. Once you have done this, open your build phases (under your project's Build Settings screen) and add the resources from inside the framework into the Copy Bundle Resources section: click the Add Other option at the bottom, then add all the Hipmob image resources (from inside the hipmob.framework folder).
  5. Include the HMChatViewController.h header file wherever you'll be launching a chat.
    #include <hipmob/HMChatViewController.h>
  6. And then create the controller and present it. You'll need to use your Hipmob application ID from step #1 above. For example, if the application ID was "2ea7d86854df4ca185af84e68ea72fe1":
        // initialize it with the appropriate app identifier, taken from the Hipmob console at https://manage.hipmob.com/#apps  
        HMChatViewController * livechat = [[HMChatViewController alloc] initWithAppID:@"2ea7d86854df4ca185af84e68ea72fe1" andUser:nil];  
    
        // the HMChatViewController is a UINavigationController, so we have access to all the navigation controller fields  
        // adjust the navigation bar's tint color to match the applications color  
        livechat.navigationBar.tintColor = [UIColor colorWithRed:145.0/255.0 green:18.0/255.0 blue:0.0 alpha:1];  
    
        // set the title of the chat window  
        livechat.body.title = @"Support Chat";  
    
        // make sure the input text field doesn't expand more than 4 lines  
        livechat.chatView.maxInputLines = 4;  
    
        // set the placeholder text shown in the input text field and the color to use  
        livechat.chatView.placeholder = @"Start chatting";  
        livechat.chatView.placeholderColor = [UIColor grayColor];  
    
        // make sure any URLs pushed open up in a   
        livechat.shouldUseSystemBrowser = FALSE;  
    
        // set the context: this tells the operator who the user is and what action the user was taking  
        [livechat.chatView updateName:@"User's Name"];  
        [livechat.chatView updateEmail:@"user@example.com"];  
        [livechat.chatView updateContext:@"Trying to reserve a hotel in Chicago"];  
    
        // set a push token (if you have one saved: this allows Hipmob to send chat messages from the operator even when   
        // the user is offline)  
        if(token){  
            [livechat.chatView setPushToken:token];  
        }  
        livechat.chatDelegate = self;  
    
        // and present  
        [self presentModalViewController:livechat animated:YES];
    			
  7. And we're complete. Build your app.
Note If you see build errors complaining about CFHTTP or Security then you missed step #2 above: just add in the dependencies in the Link Binary with Libraries section of your project's Build Phases.
To chat with a user, you will need to log into your Hipmob XMPP account using your username and password from step 1 above.
Once you are logged in, ensure that your status is set to Available (we don't send any messages to administrators marked as Away).
Now open the chat window in the app, and type something. It should pop up in your XMPP client! Go ahead and reply in your XMPP client. It should show up in the app!

15-minute integration on iPad

To see a prepackaged version, look at the Hipmob iOS experience sample on Github. This has support for both the iPhone and the iPad. You can clone the repository, open the project, open the HMiPhoneConfig.h file and stick your own key in, and you're all set! Launch it in the debugger and start chatting away.
The iPad integration works exactly like the iPhone integration: the major difference is that we use the
HMChatPopoverController
to allow chatting while the application is still in use.
  1. Perform steps #1 through #4 above.
  2. Include the HMChatPopoverController.h header file wherever you'll be launching a chat.
    #include <hipmob/HMChatPopoverController.h>
  3. And then create the controller and present it. You'll need to use your Hipmob application ID from step #1 above. For example, if the application ID was "2ea7d86854df4ca185af84e68ea72fe1":
        // initialize it with the appropriate app identifier, taken from the Hipmob console at https://manage.hipmob.com/#apps  
        HMChatPopoverController * livechatpopover = [[HMChatPopoverController alloc] initWithView:(UIView *)sender andAppID:@"2ea7d86854df4ca185af84e68ea72fe1" andUser:nil];  
    
        // the HMChatPopoverController embeds a UINavigationController, so we have access to all the navigation controller fields  
        // adjust the navigation bar's tint color to match the applications color  
        livechatpopover.content.navigationBar.tintColor = [UIColor colorWithRed:145.0/255.0 green:18.0/255.0 blue:0.0 alpha:1];  
    
        // set the title of the chat window  
        livechatpopover.content.title = @"Support Chat";  
    
        // make sure the input text field doesn't expand more than 4 lines  
        livechatpopover.content.chatView.maxInputLines = 4;  
    
        // set the placeholder text shown in the input text field and the color to use  
        livechatpopover.content.chatView.placeholder = @"Start chatting";  
        livechatpopover.content.chatView.placeholderColor = [UIColor grayColor];  
    
        // set the size of the popover  
        livechatpopover.content.contentSizeForViewInPopover = CGSizeMake(320, 240);  
    
        // set the popover's passthroughViews: this allows the chat view to float above the main ipad view  
        livechatpopover.passthroughViews = [[[NSArray alloc] initWithObjects:self.view, nil] autorelease];  
    
        // set the context: this tells the operator who the user is and what action the user was taking  
        [livechatpopover.content.chatView updateName:@"User's Name"];  
        [livechatpopover.content.chatView updateEmail:@"user@example.com"];  
        [livechatpopover.content.chatView updateContext:@"Trying to reserve a hotel in Chicago"];  
    
        // set a push token (if you have one saved: this allows Hipmob to send chat messages from the operator even when   
        // the user is offline)  
        if(token){  
            [livechatpopover.content.chatView setPushToken:token];  
        }  
        livechatpopover.content.chatDelegate = self;  
        if(token){  
            [livechatpopover.content.chatView setPushToken:token];  
        }  
        [livechatpopover presentPopoverFromBarButtonItem:(UIBarButtonItem *)sender permittedArrowDirections:UIPopoverArrowDirectionAny animated:YES];
    			
  4. Remember to keep track of the HMChatPopoverController and release it when it is no longer in use. To help with this you can use the chatViewControllerWillDismiss delegate method to determine when the controller was dismissed by the user..
  5. And we're complete. Build your app.
  6. Note As before, if you see build errors complaining about CFHTTP or Security then you didn't add the appropriate libraries: just add in the dependencies in the Link Binary with Libraries section of your project's Build Phases.
To chat with a user, you will need to log into your Hipmob XMPP account using your username and password from step 1 above: set the domain to hipmob.com.
Once you are logged in, ensure that your status is set to Available (we don't send any messages to agents marked as Away ).

Requirements

  • Familiarity with iOS development. The embedded framework comes with all the prebuilt includes so you only have to include the Framework Dependencies listed above as you would normally in Xcode.
  • SocketRocket: this library is built into our embedded framework. If you're not already using SocketRocket for Websocket support in your app then you don't need to do anything special. If you ARE using it already then you can use our bare framework which does not include SocketRocket.
  • Hipmob is compatible with apps developed for iOS 4.3 or higher.
  • As an administrator, you have to have an XMPP compatible client to connect to our servers (there are a ton of free ones: on Windows we recommend Pidgin, on OSX Adium, on Linux Empathy, on Android Xabber, and on iOS Monal or IMO. If you don't see your platform here we still love you: just reach out to us if you can't find one and we'll work with you to find one that works). Any other standards-compliant XMPP client should just work. We're also working on integration with federated XMPP servers (such as Google Talk and Facebook), and once that is ready you'll be able to use your existing messaging accounts.

Details


Framework Options

Hipmob's iOS framework depends on a WebSocket library (the excellent SocketRocket Websocket library, to be exact). If you're already using this library in your app, you should make sure you use the bare Hipmob iOS library.
Both frameworks include all the required images, so you dont need to add other files, or adjust search paths in XCode. Simply include the framework and include the appropriate header file and you are ready to go.

Framework Settings

Hipmob's iOS framework extends the standard iOS UIView, UIViewController, UIPopoverController and UINavigationController classes: you can customize the Hipmob classes the same ways you would customize any of those other classes. To learn more, read the full class documentation.
The HMChatViewController extends the UINavigationController class and provides a full navigation bar that can be styled and can have the title changed.
The HMChatPopoverController extends the UIPopoverController class and embeds an HMChatViewController instance.
The HMContentChatViewController extends the UIViewController class and provides a content view controller that can be embedded in container view controllers such as the split view controller (or your own UINavigationController).
For advanced usage, the HMChatView provides a UIView that can be added to an existing controller's layout programmatically, and sized accordingly. Properties on the class allow for custom styling.

Framework Delegates

Each of the The Hipmob iOS framework classes has a delegate protocol that can be used to keep track of changes to the class, and allow performing custom actions (for example, when URLs are sent).

Chat Sessions

Once the Hipmob framework class is launched (either the full screen or the chat view) it will automatically connect to the Hipmob communication network. The user name that will appear for the device is based on the device's name: you can customize the user name and email address using the updateName and updateEmail methods on the chat view. The Hipmob chat view handles all chat session setup and communication: it connects and identifies itself to the Hipmob communication network. This requires that the device's network connection be online and available.

Figure 1: Connecting to the Hipmob communication network

Once it successfully connects to the communication network, it checks to see if any admins are available (i.e. online and with status not Away). If it finds any, it displays the following text. This will be customizable in our next version.

Figure 2: Admins are available

If no admins are available, a different notice is displayed. This will be customizable in our next version:

Figure 3: No admins are available

User Interaction

Once the connection is established, the user can immediately start chatting: all messages will be routed to all available admins. When the first admin responds, all subsequent messages are then routed to that admin.

Figure 4: Messages on an iPhone

Figure 5: Conversation in the admin's XMPP client

User Information

As shown in Figure 5 above, useful user information can be provided to the Hipmob chat view using the updateName, updateEmail and updateContext methods on the chat view. The device's country setting is always available as that is obtained from the device: see the full range of configuration options available.

Customization: View

The appearance of the default Hipmob view controller can be modified in any of the standard iOS UIView and UIViewController ways. On the HMChatViewController the chatView and body properties will retrieve the actual chat UIView and the internal content view controller used inside the HMChatViewController instance. Similar properties exist for the HMContentChatViewController and HMChatPopoverController. If even more extensive customization is required a user interface source license can be obtained that will grant access to all the Hipmob UI source code and will allow complete customization to match your unique requirements: contact team@hipmob.com for more information about purchasing a user interface source license.

Localization

The Hipmob iOS Framework currently is still US English-only: future releases will support additional languages.

Push Notifications

Hipmob can be configured to send push notifications to the user's iOS device whenever a message is sent to them while they are offline. Read more in our iOS Push Notification guide: the setPushToken method on the HMChatView can be passed the application's push notification token (as an NSData instance) to enable push notifications.

Check Operator Availability

To only show the live chat button when an operator is available, implement the HMChatViewAvailabilityCheck protocol and then call the checkOperatorAvailabilityForApp class method of HMChatView. For example, here we call the method in the viewDidAppear function of our view controller.

- (void)viewDidAppear:(BOOL)animated  
{  
    [super viewDidAppear:animated];  

    [HMChatView checkOperatorAvailabilityForApp:@"2ea7d86854df4ca185af84e68ea72fe1" andNotify:self];  
}  
And in the delegate methods we change the background color of the live chat button to orange if there are no operators available, or green if there are operators available.
-(void)operatorOffline:(NSString *)app  
{  
    _navBar.topItem.rightBarButtonItem.tintColor = [UIColor orangeColor];  
}  

-(void)operatorAvailable:(NSString *)app  
{  
    _navBar.topItem.rightBarButtonItem.tintColor = [UIColor colorWithRed:0/255.0 green:153.0/255.0 blue:0/255.0 alpha:1];  
}

User Interface


PSD Files for in-app chat

Description
These files can be modified and renamed to replace the images in your app chat window. This allows for an incredibly deep level of customization. PSD's are attached.
iPhone 5 Design Assets iPhone 4 & 4S Design Assets