Hipmob provides hosted live chat for mobile applications. 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 experience into your Android app.

To see this already nicely packaged, download the Hipmob test project which is a fully functional Eclipse project that integrates the Hipmob Android library. Unzip it into a directory, import it into Eclipse, open the HipmobTestActivity class and stick your own key in, and you're all set! Launch it in the debugger and it will automatically open a chat window.

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.
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. This will allow sending/receiving of text, picture and audio messages.

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

   			// 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_KEY);
   
   			// REQUIRED: pass the host user identifier.
   			i.putExtra(HipmobCore.KEY_USERID, "my-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.

To chat with a user, you will need to log into your Hipmob XMPP account using your username and password from step 1 above.

• To log into Adium.
• To log into iChat.
• To log into Instantbird.
• To log into imo.
• To log into Pidgin.
• [PENDING] To log into Empathy.
• [PENDING] To log into Xabber.
• [PENDING] To log into Monal.
• If your XMPP client is not listed above, you can login using the username and password with a domain set to hipmob.com.

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!

• Hipmob integration requires familiarity with Android development: this guide assumes you are using Eclipse with the ADT plugin (but will still work if you are using Ant or Maven: we work with everyone). For simplicity it is not an Android library: it is only a JAR file you have to include in your project.
• We currently support Android development using some rapid development environments such as Titanium and Parse. We dont yet support web-based development platforms (such as Trigger.io) or alternate languages (such as C# as used by MonoDevelop): we may provide such support in the future.
• We currently require that your app be developed for devices running Android 2.0 or higher (we don't think that's unreasonable: Android 1.6 was released in September of 2009, so its been a little while).
• Your app will need (at a minimum) INTERNET privileges (hard to chat if you aren't connected to the Internet) and you'll have to add our activity definition to your AndroidManifest.xml file.
• As an administrator, you have to have an XMPP compatible client to connect to our communication network (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. 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.

Hipmob's Android library includes all necessary dependencies: drop it in and you're ready to go.

It is a standard JAR file: you'll need to add it to the build path. To do that:

1. In your Android project, create a directory named libs at the root of your project (next to src/, res/, etc.).
2. Copy the Hipmob Android JAR file to the libs/ directory.
3. In Eclipse, right-click (on Windows/Linux; on OSX it should be a a Ctrl+click, or a 2-finger click on the track pad) the Hipmob Android JAR file in the Package Explorer, select Build Path > Add to Build Path.

Once you have the library, you'll need to add the necessary entries to the Android manifest file. Hipmob for Android requires a network connection to link up to the communication network, so if you don't already use the network connection in your app you'll need to enable it. Add the appropriate permissions to the end of your AndroidManifest.xml file: at a minimum you will need the INTERNET permission.

		    <uses-permission android:name="android.permission.INTERNET" />
		  

To support picture and audio messaging, you'll also need to add the WRITE_EXTERNAL_STORAGE and RECORD_AUDIO permissions. Hipmob for Android uses progressive enhancement: if you only provide the INTERNET permission then only text messaging will be available, if you only provide the INTERNET and WRITE_EXTERNAL_STORAGE permissions then only text and picture messaging will be available, and if you provide INTERNET, WRITE_EXTERNAL_STORAGE and RECORD_AUDIO permissions then text, picture and audio messaging will be available.

		    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
		    <uses-permission android:name="android.permission.RECORD_AUDIO" />
		  

You'll also need to register the Hipmob Activity to be launched as part of your app: the Activity class is com.hipmob.android.HipmobCore and can be added to your AndroidManifest.xml file very easily:

		    <activity android:name="com.hipmob.android.HipmobCore" />
		  

And that's it. As a complete example, this is the AndroidManifest.xml file from the test project Download the Hipmob Android Testing Project Source Code: it shows the permissions as well as the Activity registration (WRITE_EXTERNAL_STORAGE and RECORD_AUDIO are optional).

		    <?xml version="1.0" encoding="utf-8"?>
		    <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.hipmob.android.testing" android:versionCode="1" android:versionName="1.0" >
		    <uses-sdk android:minSdkVersion="5" />
		    <application android:icon="@drawable/ic_launcher" android:label="@string/app_name" >
		    <activity android:name=".HipmobTestActivity" android:label="@string/app_name" >
		    <intent-filter>
		    <action android:name="android.intent.action.MAIN" />
		    <category android:name="android.intent.category.LAUNCHER" />
		    </intent-filter>
		    </activity>
		    <activity android:name="com.hipmob.android.HipmobCore" android:label="Hipmob" />
		    </application>
		    <uses-permission android:name="android.permission.INTERNET"/>
		    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
		    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
		    </manifest>
		  

Once the HipmobCore Activity is registered in your app's manifest, you can start it by creating an appropriate Intent from inside any other Activity or Service in your app. When creating the Intent, you must pass your application ID as an extra: this is used to identify the admins for the chat session that will be launched, as shown below.

// 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_KEY);

		    // REQUIRED: pass the host user identifier.
		    i.putExtra(HipmobCore.KEY_USERID, "my-user-identifier-that-is-unique");

		    // launch the chat window
		    startActivity(i);

The HipmobCore Activity handles all chat session setup and communication: it connects to the Hipmob communication network and identifies itself. This requires that the device's network connection be online and available.

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 pops a notice up. The notice displayed when admins are available can be customized.

If no admins are available, a different notice is displayed: as before, the notice displayed can be customized.

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. Responses are timestamped to show when they are sent, and the client keeps a history of all messages sent or received. Send picture or audio messages by clicking on the action bar button.

As shown in Figure 5 above, useful user information can be provided to the HipmobCore Activity as configuration options: this information can include the user's name or email, as well as other items. The device's country setting is always available: other information is shown if it is provided by the app that is integrating Hipmob: see the full range of configuration options available.

The title shown in Figure 2 and 3 above can be customized by the developer: it can include (for example) the admin's name. See the Title configuration options for more information.

The notices shown in Figure 2 and 3 above can also be customized: this allows the developer to use language that matches their app. See the Present/Away Notices configuration options for more information.

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

Hipmob stores messages received when a device is unavailable (offline message delivery): any messages sent to a specific device when it is offline are stored and when the device connects those messages are delivered. To help you make the most of this the Hipmob library provides an interface to check for pending messages: this can be used to display message waiting indicators or badges.

		    HipmobRemoteConnection.checkPendingMessages(this, HIPMOB_KEY, 
		    new HipmobPendingMessageListener(){
		    @Override
		    public void pendingMessageCount(int count) {
		    // <count> is the number of pending messages. If no messages are available it will be 0.
		    // TODO: notify the user somehow that messages are waiting.
		    }

		    @Override
		    public void pendingMessageLookupFailed() {
		    // TODO: ignore, or notify the user that an error occured performing the lookup.
		    }
		    });
		

Hipmob can be configured to send push notifications to the user's Android device whenever a message is sent to them while they are offline. Read more in our Android Push Notification guide.

All configuration options are provided to the HipmobCore Activity using Android Intent extras. The options are listed below with usage examples.

The unique identifier that distinguishes this application from any other application that uses the Hipmob network. Provided by the Hipmob management console.

Yes

Version 1.0

If the application ID provided by the console is fefed30c17f0409f89d5a4953c0fce1f, then it would be used like this:

		    // 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");

		    // launch the chat window
		    startActivity(i);

                  

We recommend the use of a class final static variable to minimize the possibility that the application ID is incorrectly defined anywhere. As an example, if you have an Activity called MyMainActivity, in that Activity you could define your key like this:

		    public static final String HIPMOB_KEY = "fefed30c17f0409f89d5a4953c0fce1f";
		  

You can then use this value everywhere you want to be able to open a chat window:

		    i.putExtra(HipmobCore.KEY_APPID, MyMainActivity.HIPMOB_KEY);
		  

This will be the style we will use going forward.

The application can provide a user identifier that is passed back to the Hipmob communication network. This user identifier will allow an admin to extract chat transcript data associated with this device using the Hipmob API. The user 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.

Yes

Version 1.0

		    // 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 user identifier
		    i.putextra(HipmobCore.KEY_USERID, "my-magical-user-identifier");

		    // launch the chat window
		    startActivity(i);
                  

Note Because Hipmob does not parse the provided user identifier or look at it in any other way, the Hipmob communication network will accept the same user identifier for multiple devices. Note that future functionality may depend on uniqueness of the user identifier.

The application can provide the name of the user on the device to the Hipmob chat activity, which is passed back to the Hipmob communication network. This name will be used in the chat conversation with the admin and will be saved to the conversation transcript: the admin can provide more personalized responses with this information.

No

Version 1.0

		    // 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 user's name
		    i.putextra(HipmobCore.KEY_NAME, "Jack Hawksmoor");

		    // launch the chat window
		    startActivity(i);
                  

The application can provide the email address of the user on the device to the Hipmob chat activity, which is passed back to the Hipmob communication network. This email will be used in the chat conversation with the admin and will be saved to the conversation transcript: the admin can provide more personalized responses with this information.

No

Version 1.0

		    // 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 user's email
		    i.putextra(HipmobCore.KEY_EMAIL, "jack@theauthority.com");

		    // launch the chat window
		    startActivity(i);
                  

The application can provide a generic location of the device to the Hipmob chat activity, which is passed back to the Hipmob communication network. This location will be used in the chat conversation with the admin and will be saved to the conversation transcript: the admin can provide more personalized responses with this information. It can be used in conjunction with the Latitude/Longitude configuration options, or independently.
Note If this value is obtained from the GPS location functionality on the device, be certain to inform the user and obtain the necessary consent to transmit their location information.

No

Version 1.0

		    // 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 user's location string
		    i.putextra(HipmobCore.KEY_LOCATION, "Tokyo, Japan");

		    // launch the chat window
		    startActivity(i);
                  

The application can provide GPS co-ordinates (latitude and longitude) to the Hipmob chat activity, which are passed back to the Hipmob communication network. This location detail is not displayed in the chat conversation but will be associated with the conversation and device and will be used in the upcoming Hipmob API. It can be used in conjunction with the Location configuration option, or independently.
Note If this value is obtained from the GPS location functionality on the device, be certain to inform the user and obtain the necessary consent to transmit their location information.

No

Version 1.0

com.android.hipmob.HipmobCore.KEY_LATITUDE, com.android.hipmob.HipmobCore.KEY_LONGITUDE

		    // 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 user's geolocation
		    i.putExtra(HipmobCore.KEY_LATITUDE, 37.423105);
		    i.putExtra(HipmobCore.KEY_LONGITUDE, -122.082399);

		    // launch the chat window
		    startActivity(i);
                  

Note The latitude and longitude values provided must be in decimal degrees.

The application can provide context information that is displayed to the admin who accepts the chat. This can be used to indicate where the user came from (if the chat can be launched from multiple places within the app) or what difficulties the user was experiencing (if the chat is launched from a help button or link in the app). The context will be used in the chat conversation with the admin and will be saved to the conversation transcript: the admin can provide more personalized responses with this information. The upcoming Hipmob API will allow searching on specific context strings: this could be used to identify important issues customers are facing.

No

Version 1.0

		    // 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 user's context information
		    i.putextra(HipmobCore.KEY_CONTEXT, "On the Carrier");

		    // launch the chat window
		    startActivity(i);

The application can customize the notices displayed if an admin is present or if an admin is away. These values are entirely local to the app and are not sent to the Hipmob communication network.

No

Version 1.0

com.android.hipmob.HipmobCore.KEY_AWAY_NOTICE, com.android.hipmob.HipmobCore.KEY_PRESENT_NOTICE

		    // 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 present and away notices
		    i.putExtra(HipmobCore.KEY_AWAY_NOTICE, "Nobody home: drop us a line, we'll get back to you.");
		    i.putExtra(HipmobCore.KEY_PRESENT_NOTICE, "We're right here: what can we help you with?");

		    // launch the chat window
		    startActivity(i);

The application can customize the title displayed on the chat Activity: this can be (for example) the application's name. This value is entirely local to the app and is not sent to the Hipmob communication network.

No

Version 1.0

		    // 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 title of the chat window
		    i.putExtra(HipmobCore.KEY_TITLE, "Chat with the Engineer");

		    // launch the chat window
		    startActivity(i);