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:
    • SystemConfiguration.framework
    • CoreTelephony.framework
    • CoreGraphics.framework
    • Foundation.framework
    • UIKit.framework
    • CFNetwork.framework
    • CoreData.framework
    • libicucore.dylib
    • Security.framework
    • QuartzCore.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 HMService.h header file in your application delegate, then initialize the service inside your didFinishLaunchingWithOptions method.
    // setup the Hipmob shared service
    [[HMService sharedService] setup:APPID withLaunchOptions:launchOptions];
  6. Once initialized, provide the Hipmob service with the user identifier: you can use any identifier you'd like, such as an email address or a UUID.
    [[HMService sharedService] setUser:userid];
    If you need to generate a random unique user identifier, you can use the NSUUID library:
    NSUserDefaults * prefs = [NSUserDefaults standardUserDefaults];
    if(![prefs valueForKey:@"userid"]){
      [prefs setValue:[[NSUUID UUID] UUIDString] forKey:@"userid"];
      [prefs synchronize];
    }
    NSString * userid = [prefs valueForKey:@"userid"];
    			
  7. You can then open a chat view controller from anywhere in your application using the following code.
    [[HMService sharedService] openChat:parentViewController withSetup:^(HMChatViewController * livechat){
            // 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];
    
            // make sure the input text field doesn't expand more than 4 lines
            livechat.chatView.maxInputLines = 4;
    
            // set the font and color for the chat messages
            livechat.chatView.sentMessageFont = [UIFont systemFontOfSize:10.0];
            livechat.chatView.sentTextColor = [UIColor grayColor];
            livechat.chatView.receivedMessageFont = [UIFont systemFontOfSize:12.0];
            livechat.chatView.receivedTextColor = [UIColor brownColor];
    
            [livechat.chatView updateName:@"User's Name"];  
            [livechat.chatView updateEmail:@"user@example.com"];  
            [livechat.chatView updateContext:@"Trying to reserve a hotel in Chicago"];  
    
            // make sure any URLs pushed open up in an internal browser
            livechat.shouldUseSystemBrowser = FALSE;
        } forApp:APPID];
    			
  8. 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 #6 above.
  2. 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":
    [[HMService sharedService] openChatViewInPopoverFromBarButtonItem:(UIBarButtonItem *)currentItem inDirection:(UIPopoverArrowDirection)direction withSetup:^(HMChatPopoverController * livechat){
                // set the popover content size
                controller.popoverContentSize = CGSizeMake(320, 240);
    
                // pass through: this lets us interact
                controller.passthroughViews = [[NSArray alloc] initWithObjects:self.view, 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
                controller.content.navigationBar.tintColor = [UIColor colorWithRed:145.0/255.0 green:18.0/255.0 blue:0.0 alpha:1];
    
                // make sure the input text field doesn't expand more than 4 lines
                controller.content.chatView.maxInputLines = 4;
    
                // set the font and color for the chat messages
                controller.content.chatView.sentMessageFont = [UIFont systemFontOfSize:10.0];
                controller.content.chatView.sentTextColor = [UIColor grayColor];
                controller.content.chatView.receivedMessageFont = [UIFont systemFontOfSize:12.0];
                controller.content.chatView.receivedTextColor = [UIColor brownColor];
    
                // set the context: this tells the operator who the user is and what action the user was taking  
                [controller.content.chatView updateName:@"User's Name"];  
                [controller.content.chatView updateEmail:@"user@example.com"];  
                [controller.content.chatView updateContext:@"Trying to reserve a hotel in Chicago"];  
    
                // make sure any URLs pushed open up in an internal browser
                controller.content.shouldUseSystemBrowser = FALSE;
        } forApp:@"2ea7d86854df4ca185af84e68ea72fe1"];
    			
  3. And we're complete. Build your app.
  4. 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