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

Peer to Peer Chat with Hipmob


Overview

Hipmob provides hosted live chat for mobile apps. You sign up with us, we give you a code, you download our library, you integrate it into your app, and you can then talk to your users, figure out what they want and what problems they are having, and make them happy. No servers, 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 peer-to-peer experience into your iPhone or iPad app(s).

Availability

Hipmob peer-to-peer chat is currently available for iOS and for Android.

Background

Hipmob supports both support chat (covered in the standard Android and iOS documentation) and peer-to-peer chat (covered here). The only difference between peer-to-peer chat and support chat is that for peer-to-peer chat a peer has to be specified. For support chat no peer is necessary: our communication network routes the messages to any available operators.
Specifying the peer is straightforward: you use your app's existing user identifiers as Hipmob device identifiers.
Note Because Hipmob does not parse the provided device identifier or look at it in any other way, the Hipmob communication network will accept the same device identifier for multiple devices. Note that future functionality may depend on uniqueness of the device identifier.

Quick Start - Android

To integrate Hipmob into your own project, read on.
  1. Register for an account at https://manage.hipmob.com/ (if you haven't already done so). Once you register a Hipmob application entry will be created for you and an application ID will be generated. Remember this application ID: you'll use it later.
  2. Download the Hipmob Android library JAR file. This includes all the dependencies required (see the Library Options section for more details).
  3. Copy the Hipmob library JAR file into your project's library folder (libs, if you're using the default project folder structure in Eclipse).
  4. Add the Hipmob library JAR file into your project's build path.
  5. Add the INTERNET, WRITE_EXTERNAL_STORAGE and RECORD_AUDIO permissions to the AndroidManifest.xml file.
    			  
    			<uses-permission android:name="android.permission.INTERNET" />
    			<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    			<uses-permission android:name="android.permission.RECORD_AUDIO" />
    		      
  6. Add the HipmobCore activity definition to the AndroidManifest.xml file.
    			<activity android:name="com.hipmob.android.HipmobCore" />
    		      
  7. Use an Intent to call the HipmobCore activity. You'll need the application ID from step 1: pass that as HIPMOB_APPID. You will also need to set the host application device id, and then specify the peer to chat with.
    			// create an intent
    			Intent i = new Intent(this, com.hipmob.android.HipmobCore.class);
    			
    			// REQUIRED: set the appid to the key you're provided
    			i.putExtra(HipmobCore.KEY_APPID, HIPMOB_APPID);
    
    			// REQUIRED: pass the host application identifier.
    			i.putExtra(HipmobCore.KEY_USERID, "my-user-identifier-that-is-unique");
    
    			// REQUIRED: pass the peer's host application identifier.
    			i.putExtra(HipmobCore.KEY_PEER, "their-user-identifier-that-is-unique");
    
    			// launch the chat window
    			startActivity(i);
    		      
    Connect it to a button (you can see an example in the WanderPlayer app in the Google Play Store).
  8. And we're complete. Build your app.

Quick Start - iOS

To integrate Hipmob into your own iOS project, read on.
  1. Register for an account at here (if you haven't already done so). Once you register a Hipmob application entry will be created for you and an application ID will be generated. Remember this application ID: you'll use it later.
  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" you'll need to use that. You must also specify the user identifier and the peer identifier: you'd use unique values that your app associates with the 2 users who should communicate.
        // 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:@"" andPeer:@""];  
    
        // 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.

Details


Managing Friends

To prevent sending and receiving of spam messages Hipmob requires the use of friend lists that keep track of which devices are permitted to send/receive messages from one another. The friend list can be managed using the Hipmob Server API.

Android Configuration Options


All configurations options documented in the Android guide can be used: peer-to-peer functionality provides an additional configuration option to specify the chat recipient.

Peer

Description
The application must provide the peer's device identifier. This is passed back to the Hipmob communication network and is used to route messages to the appropriate device. The device identifier is treated as an opaque key by the Hipmob communication network: it is not parsed or processed in any way, just stored. If present, it is written out into the transcripts.
Required
Yes
Since:
Version 1.0 (Beta 2)
Extra Name:
com.android.hipmob.HipmobCore.KEY_PEER
Usage
		    // create an intent
		    Intent i = new Intent(this, com.hipmob.android.HipmobCore.class);

		    // REQUIRED: set the appid to the key you're provided
		    i.putExtra(HipmobCore.KEY_APPID, "fefed30c17f0409f89d5a4953c0fce1f");

		    // set the device identifier
		    i.putextra(HipmobCore.KEY_DEVICEID, "my-magical-device-identifier");

		    // REQUIRED: pass the peer's host application identifier.
		    i.putExtra(HipmobCore.KEY_PEER, "their-device-identifier-that-is-unique");

		    // launch the chat window
		    startActivity(i);
                  
Note Because Hipmob does not parse the provided device identifier or look at it in any other way, the Hipmob communication network will accept the same device identifier for multiple devices. Note that future functionality may depend on uniqueness of the device identifier.

Peer

Description
This application must provide the peer's user identifier when instantiating the HMChatViewController. This is passed back to the Hipmob communication network and is used to route messages to the appropriate user. The identifier is treated as an opaque key by the Hipmob communication network: it is not parsed or processed in any way, just stored. If present, it is written out into the transcripts.
Required:
NO
Since:
Version 1.3
Type:
NSString
Usage:
For peer-to-peer connections, set this value when constructing the HMChatViewController or HMChatView.
HMChatViewController * livechat = [[HMChatViewController alloc] initWithAppID:@"2ea7d86854df4ca185af84e68ea72fe1" andUser:@"" andPeer:@""];
Note Because Hipmob does not parse the provided identifier or look at it in any other way, the Hipmob communication network will accept the same identifier for multiple devices. Note that future functionality may depend on uniqueness of the identifier.