What is pushMobi?

Push messages are special messages that display an alert on your mobile phone associated with a particular application. On the iOS platform, the application icon will display a badge featuring the number of messages waiting for the user. On the Android platform, a smaller icon featuring a similar badge will appear at the upper left hand corner of the operating system to indicate that a message is waiting.


iOS Badge Example	Android Badge Example

The appMobi pushMobi package is a cross platform push messaging service for mobile applications. It allows developers to design and write code to handle push messaging once for both Android and iOS platforms. It supports both simple and rich media messages. Simple push messages consist of 140 characters of message text and may include an optional data string and user key string. The data string can be used to initiate a behavior in the application, while the user key is logged with statMobi push events.

Rich media push messages allow applications to deliver more robust content. In addition to the same text and data that make up a simple message, rich messages include either a target URL or embedded HTML which will be loaded in the application. Whether the media is delivered over the Internet or embedded in the application, rich messages can deliver just about any type of Web-enabled media such as images, video, audio, HTML5 canvas elements and more.

Adding pushMobi to an appMobi Application

In order to enable an application to receive pushMobi messages, an appMobi application must be built to register the device or the user of the device with the pushMobi server.

Requirements

Push messaging on Android devices requires the Android 2.2 operating system or above. In order to get push messages on an iOS device, the device must be on version 3.2 or above.

Register the application on the device

Registering a user id on a particular device alerts the pushMobi service that the application is installed and ready to receive push messages. The first time a pushMobi-enabled application runs, it should establish a user identifier on the device for that particular appMobi application. The user identifier doesn't necessarily have to be entered in by the user, since it could be generated randomly or based on the device ID. However, developers looking to reach users only once despite those users having several devices will have to make sure that the user id is unique to each human being who uses the application regardless of which device they are currently holding in their hand. For example:


document.addEventListener("appMobi.device.ready", registerForMessages, false);
//register this app/user with the push messaging system.
//This should only happen once per install
function registerForMessages() {
	//Get the unique identifier of this device
	myUserID = AppMobi.device.uuid; //set a default unique username for the purposes of push
	chosenPassword = "";
	chosenEmail = "";
	//If this device is already registered, just check for new notifications
	if (AppMobi.cache.getCookie("pushmobi_username") == undefined) {
		try {
			//if you want the user to get the same notifications on multiple devices,
			//you must get a username from the user, if not, bypass the following prompts
			chosenUsername = prompt("Choose a username for push messaging", myUserID);
			chosenPassword = prompt("Choose a password for push messaging", "password");
			chosenEmail = prompt("Enter an email address for account confirmation", "");
			AppMobi.notification.addPushUser(chosenUsername, chosenPassword, chosenEmail);
		} catch (e) { alert("error adding push user: " + e.message); }
	}
}

Once the application is successfully registered with the push messaging server, the appMobi.notification.push.enable event is fired. At that point, the username, password, and recovery email address may be cached on the application.


function notificationsRegistered(event) {
	if (event.success == false) {
		if (didcheckuser == false) {
			AppMobi.notification.checkPushUser(chosenUsername, chosenPassword);
			didcheckuser = true;
		}
		else {
			alert("There was an error adding push notifications " + event.message);
		}
		return;
	}
	else {
		//if the app successfully registered, it's good to save the user information
		//for pulling the right the messages that belong to this user. Then you
		//can prevent unnecessarily trying to re-register the app/user
		AppMobi.cache.setCookie("pushmobi_username", chosenUsername, -1);
		AppMobi.cache.setCookie("pushmobi_password", chosenPassword, -1);
		AppMobi.cache.setCookie("pushmobi_email", chosenEmail, -1);
	}
	updateNotifications();
}
document.addEventListener("appMobi.notification.push.enable", notificationsRegistered, false);

Capture message events

Once the application has successfully registered for push messages, the next step is to start looking for message events. The sample below is called from the code block above, and it will begin to listen for the appMobi.notification.push.receive event which indicates that a new pushMobi message is available.


function updateNotifications(event) {
	try {
		var myNotifications = AppMobi.notification.getNotificationList();
		var len = myNotifications.length;
		for (i = 0; i < len; i++) {
			//get the pushMobi message data
			msgObj = AppMobi.notification.getNotificationData(myNotifications[i]);
			//display the pushMobi message as a notification if there is no data
			if (msgObj.isRich == false) { //Is this a simple text push message?
				//YOUR CODE HERE - possibly do something more interesting than alert the text
				alert(msgObj.msg);
				//////
				//remove the message from the server otherwise the app will
				//think it has more messages waiting for it
				AppMobi.notification.deletePushNotifications(msgObj.id);
			} else { //Show rich push messages in the rich viewer
				AppMobi.notification.showRichPushViewer(msgObj.id, 10, 10, 10, 10, 80, 80);
				break; // only one rich message at a time, will resume after richViewerClosed
			}
		}
	}
	catch (e) { alert("error in updateNotifications: " + e.message); }
}
//register to be notified when a push message is received by the app
document.addEventListener('appMobi.notification.push.receive', updateNotifications, false);

//Two rich push msgs, can't be viewed at the same time
//register to be notified when a rich push message is closed
document.addEventListener("appMobi.notification.push.rich.close", richViewerClosed, false);
function richViewerClosed(event) {

//remove the message from the server
AppMobi.notification.deletePushNotifications(event.id);

// resume viewing push messages
updateNotifications();
}

Testing pushMobi in the XDK

Using the XDK alone, you can test how your application will respond to pushMobi messages. To send a test pushMobi message in the XDK, click the pushMobi link on the left-hand side of the XDK. That link should bring up the pushMobi Cloud Services page. Select the "XDK Emulator" radio button if it isn't already selected. Click the next button.

The next screen describes the difference between simple and rich media push messages. Click Next to continue.

From the next screen, select the "simple message" radio button. Enter text to display in the message (140 characters maximum). Leave the data string and user keys blank for XDK test messages. The data string gives developers a method of transmitting data along with a pushMobi message that is hidden from the end user. This data string also has a maximum size of 140 characters. Click the next button to choose how to emulate the display of the push message in the XDK.

By selecting the "App Running" option, the application will execute as though a push message was just sent while the application was running. Selecting the "App Closed" option will cause the application to act as though it is closed when the push message is sent. That way, the application is only executed if it is triggered as a result of the push message.

Click the send button to emulate the push message. The Cloud Services display will immediately disappear, and the appMobi.notification.push.receive event will be thrown indicating to the application that a pushMobi message has arrived.

Testing pushMobi on Device

The appMobi "Test Anywhere" feature allows developers to test pushMobi messages on their mobile devices as well. Once an application appears to run smoothly using the XDK emulator to send push messages, developers should click the "Test Anywhere" icon across the top of the XDK to push their application to the cloud for testing.

To send a test pushMobi message to an application running on device using the "Test Anywhere" feature, click the pushMobi link on the left-hand side of the XDK. That will bring up the pushMobi Cloud Services page.

Click the box to enable pushMobi services for the application to test. Although there is no charge for testing pushMobi using the "Test Anywhere" feature, developers must opt-in to the pushMobi Cloud Service in order to engage the functionality for the test.

Select the Test Anywhere radio button, and then click Next to continue.

Compose another simple message by entering up to 140 characters in the Message Text field. Click Next to send the message. The XDK should display a message box indicating that the push message has been sent.

Finally, developers should run the test application on their device. That process includes downloading appMobi's test container application and browsing to specific link on the Internet. For instructions on how to run a specific application on a device using the "Test Anywhere" feature, click the "Send app Link" icon across the top of the XDK.

Be aware that pushMobi push messages may take up to 120 seconds to reach the device from the time it was sent if the application is on, and up to 10 minutes if the application is not running on the test device. When the message arrives, it should fire off the appMobi.notification.push.receive event. The code of the application should handle that event and display the message appropriately.

Using pushMobi in Production

Finally, push messages may be sent to applications that have been built for production using appMobi's build system. There are two methods of sending push messages to applications out "in the wild". The simplest method is to use appHub to send messages.

From the XDK, click the pushMobi link on the left-hand side of the XDK to bring up the pushMobi Cloud Services page. Select the Production radio button and click Next.

You will be taken to appHub with the application you are working with expanded.

Select the pushMobi icon and follow the step-by-step instructions on appMobi appHub to compose the message content, select the recipients of the message, and send the message.

For developers who want to customize their application services for their customers appMobi offers access to a pushMobi web service as well. This allows developers to build their own custom push messaging websites to reach users of their mobile applications.