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

Android Push Notifications with Hipmob


Overview

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 the integration of Android push notifications with the Hipmob platform.
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. This simplifies the developer's work: using a few configuration settings in the Hipmob management interface and by adding a few lines of configuration and code to their Android app Hipmob will prompt the user to launch their app whenever any message is received for a user (either a support message or direct message from another user of their app). Hipmob's push notification integration uses Google Cloud Messaging (GCM): below we walk through configuring GCM, passing the GCM configuration to the Hipmob communication network and then configuring your application to receive GCM messages.

Setup

Visit the Google API Console page to setup Google Cloud Messaging for Android.

Figure 1: Google API Console

If this is the first time you're using the Google API Console, you'll get a prompt as shown in Figure 2 below. You can either create a new project or use an existing project.

Figure 2: First time prompt

Enabling Google Cloud Messaging

Click on the Services button as shown in Figure 3 below to open the list of project services.

Figure 3: Project services

Scroll down and enable Google Cloud Messaging as shown in Figure 4 below.

Figure 4: Enabling Google Cloud Messaging for Android

Sender ID

Click on the Overview button to return to the main project page: this will show the project number. Save this number, as you will need it when configuring your Android application.

Figure 5: Sender ID

Server API Key

Click on the API Access button in Figure 5 above, then click on the Create new Server key... button to add a Server API key.

Figure 6: Create Server Key

This will pop open the dialog shown in Figure 7 below. Click the Create button.

Figure 7: Server Key Configuration

You will then see the server key: save that key for the next step.

Figure 8: Server Key

Enabling Push

Log into your Hipmob account and go to the Apps page (at https://manage.hipmob.com/#apps). Click the Settings button.

Figure 9: application Settings

Select the Push Notifications option.

Figure 10: Push Notifications settings screen

Paste the server API key from Figure 8 above into the GCM API Key field, and then check the Enable Android Push Notifications option.

Figure 11: Android push notification setup

And the Hipmob setup is complete. For security reasons the API key will NOT be shown. If an API key is set the Clear button will be displayed.

Figure 12: push notifications successfully setup

Android Manifest

The Android configuration is outlined at http://developer.android.com/guide/google/gcm/gs.html#android-app and http://developer.android.com/google/gcm/client.html: the application will need the correct permissions and then will need to pass the GCM registration ID to the Hipmob communication network. Ensure that you've added the Google Play Services SDK to your project as required.

Figure 13: adding the Google Play Services SDK to your application

Then edit the Android Manifest and add the required permissions. First the C2DM permission required to receive GCM messages.
		      <permission android:name="{PACKAGE NAME}.permission.C2D_MESSAGE" 
		      android:protectionLevel="signature" />
		      <uses-permission android:name="{PACKAGE NAME}.permission.C2D_MESSAGE" /> 
		    
Remember to replace {PACKAGE NAME} with the package name for your application.
Then add the other required permissions.
		      
		      <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
		      
		      <uses-permission android:name="android.permission.INTERNET" />
		      
		      <uses-permission android:name="android.permission.GET_ACCOUNTS" />
		      
		      <uses-permission android:name="android.permission.WAKE_LOCK" />
		    
Note that you may have to also add the
<uses-permission android:name="android.permission.VIBRATE" />
permission if you want the phone to vibrate when a status notification is displayed.
Add the Hipmob Play Services push notifications receiver and service.
<receiver
		      android:name="com.hipmob.android.HipmobPlayPushReceiver"
		      android:permission="com.google.android.c2dm.permission.SEND">
		      <intent-filter>
		      <action android:name="com.google.android.c2dm.intent.RECEIVE" />
		      <category android:name="{PACKAGE NAME}" />
		      </intent-filter>
		      </receiver>
		      <service android:name="com.hipmob.android.HipmobPlayPushService" />
		    
As before, remember to replace {PACKAGE NAME} with the package name for your application.
Configuration of the Hipmob push integration is done by adding the settings values to the AndroidManifest.xml file. These settings can point to values in the strings.xml file, allowing localization of any values. These should be added immediately after the com.hipmob.android.HipmobPushService entry above.
<meta-data android:name="hipmob_push_sender_ids" android:resource="@string/sender_ids" />
		      <meta-data android:name="hipmob_notification_target" android:resource="@string/notification_target" />
		      <meta-data android:name="hipmob_notification_text" android:resource="@string/notification_message_multiple" />
		      <meta-data android:name="hipmob_notification_text_single" android:resource="@string/notification_message_single" />
		    
For more details about the configuration options, see the Advanced Options section.

Android Resources

The push messages sent include a count field: this can be used in the Android status notifications to display the messages. Add the actual values to the strings.xml file. Notice the sender_ids entry is the project number from Figure 5 above.
<string name="sender_ids">97624163671</string>
		      <string name="notification_message_multiple">You have {{count}} new messages.</string>
		      <string name="notification_message_single">You have 1 new message.</string>
		      <string name="notification_target">{YOUR ACTIVITY CLASS}</string>
		    
This adds the sender ID that will be used for the HipmobPushService, sets the text that will be used for the notification messages (using the {{count}} template variable), and sets the class that will be launched when the notification gets tapped.
For more details about the configuration options, see the Advanced Options section.
Note that the status notification that is displayed will only vibrate the phone if the android.permission.VIBRATE permission is present in the AndroidManifest.xml file.

Code

Finally, in your Activity's onCreate method, initialize the Hipmob push notification integration.
protected void onCreate(Bundle savedInstanceState) {
		    HipmobPlayPushService.setup(this);
		  
And that's it. This will:
  1. Retrieve the configuration variables from the strings.xml file.
  2. Request the appropriate registration ID from the Google Cloud Messaging service.
  3. The next time a chat session is opened to the Hipmob communication network the registration ID will be saved for that device.
If your application supports having a user log out and you want to stop the push notifications from being disabled you should call HipmobPlayPushService.teardown(this);: this will manually unregister from the Google Cloud Messaging service.
Note The push notification registration ID will not be sent to the Hipmob server until a chat session is open.

Testing

To test that the push notifications are properly setup you can use the Hipmob management interface to send a message to a device. Log into the Hipmob management interface and visit the Devices tab (at https://manage.hipmob.com/#devices).

Figure 14: Devices tab

Find the device you want to send a message to, and then expand the device's menu and select Send Message.

Figure 15: Send Message

Type in the message text, and then click Send.

Figure 16: Message sent

On the Android device, the push notification will be received and displayed using the configured notification text. Notice the count of available messages has been included in the message.

Figure 17: push notification delivered

When the notification is tapped on, the configured Activity will be launched.

Figure 18: opened the Activity

Advanced Options

The Hipmob push notification integration can be configured using metadata set in the AndroidManifest.xml file as shown above: this can be used to localize the text displayed in the status notification as well as the Activity launched when the notification is tapped. The available options are discussed below.

Sender ID

Description
The Google Cloud Messaging sender ID(s) that will be used for push notifications.
Metadata Name
hipmob_push_sender_ids
Required
YES
Notes
Multiple Sender IDs can be specified by setting the value to a comma-separated string. All the sender IDs will be submitted to the Google Cloud Messaging service for registration and the registration ID returned can then be used by any server API key that is valid for any of the specified Sender IDs.
Examples
<meta-data android:name="hipmob_push_sender_ids" 
			android:resource="@string/sender_ids" />
<string name="sender_ids">97624163671</string>

Target Activity

Description
The full class name (including package name) of the Activity that should be launched when the notification is tapped.
Metadata Name
hipmob_notification_target
Required
YES
Notes
The Activity MUST be properly defined in the AndroidManifest.xml file otherwise an error will occur when the notification is tapped.
Examples
<meta-data android:name="hipmob_notification_target" 
			android:resource="@string/notification_target" />
<string name="notification_target">com.hipmob.android.StatusActivity</string>

Notification Text

Description
The text of the status bar notification.
Metadata Name
hipmob_notification_text
Required
YES
Notes
The push notification that is sent includes the number of available messages as an integer. The notification text can include a template variable {{count}}: when the status bar notification is created the template variable will be replaced with the actual number of available messages.
Examples
<meta-data android:name="hipmob_notification_text" 
			android:resource="@string/notification_text" />
<string name="notification_text">You have {{count}} new messages.</string>

Notification Text (Single)

Description
The text of the status bar notification when there is only 1 message available. This simplifies ensuring that the status bar notification language is correct for single/multiple available message counts.
Metadata Name
hipmob_notification_text_single
Required
NO
Notes
No template replacement occurs with the single message notification text. If this value is not specified then the hipmob_notification_text value will be used for all message counts: a count of 1 will be used if only 1 message is available.
Examples
<meta-data android:name="hipmob_notification_text_single" 
			android:resource="@string/notification_text_single" />
<string name="notification_text_single">You have 1 new message.</string>

Notification Title

Description
The title of the status bar notification.
Metadata Name
hipmob_notification_title
Required
NO
Notes
If this value is not specified then the application's name (as retrieved from the AndroidManifest.xml file) will be used as the title of the status bar notification.
Examples
<meta-data android:name="hipmob_notification_title" 
			android:resource="@string/notification_title" />
<string name="notification_title">Hipmob Founders</string>