Edit on March 7, 2013: Please read this blog entry.
In this blog post I'll be using Android. Only the initial setup aspects though will be Android specific, The PhoneGap code we use later should work fine in iOS as well.
Note though that you will need to get your hands dirty a bit and work with Java. You don't need to actually write any Java, but this does mean that PhoneGap Build will not be an option for apps making use of notifications. I used Eclipse for my application but you can probably get away with just using the command-line tools with PhoneGap.
Part One - Eclipse/Java Setup
Ok, so let's get started. First - create an Android PhoneGap project. I used the AppLaud plugin to make it super easy. I tend to be antsy about such things so before I did anything else I confirmed it ran on my mobile device. Also, I assume you have some Parse.com application already created. I'm not talking about a mobile application I mean an application defined at Parse's web site. I made use of my CowTipLine application.
Go to the Parse downloads and get the Android SDK. Note that this SDK is just a jar file (Parse-1.1.6.jar). Copy this jar file to your PhoneGap project's libs folder:
At this point you probably want to refresh the view in Eclipse so it recognizes a new file. As we all know, Eclipse gets snooty if you dare to actually use your file system.
Now - following along the Android notifications docs, you're asked to modify your AndroidManifest.xml to add the following lines:
These lines basically act as a listener for Parse.com push notifications. They will enable your application to recognize and respond to the notifications sent out by the server.
The Parse docs then tell you to add three sets of permissions, but by default PhoneGap already has two of them set. You should only need to add the RECEIVE_BOOT_COMPLETED permission from the set below:
Ok, now you need to get into the Java a bit. When you created your application, you had to give it a package name. I called mine org.camden.test1. I ended up with a Java file called MyPhoneGapActivity.java. You can find this under the src folder.
Do not worry about the com.borismus.webintent folder. You will not have it yet and we'll come to that later.
You don't normally need to edit this file if you use the AppLaud plugin. If you built the project by hand following the PhoneGap Android guide then you have already worked with this file a bit.
Get this file open, and do the following:
- Add an import com.parse.*; below your other imports.
- Add a Parse.initailize(this, a, b) line in your onCreate method. "a" is your application key and "b" is your client key.
- Finally, add PushService.subscribe(this, "", MyPhoneGapActivity.class). Your "So and So.class" will differ depending on the name of your file. This line handles telling the application to listen in for messages from Parse. Parse supports multiple channels for filtered notifications, but the empty string represents the "broadcast" channel.
Here is my entire Java file.
Ok, at this point you want to ensure the application still compiles. Hit the nice little green arrow Eclipse button to rerun the application. In theory, you will see nothing different, but you want to ensure it at least runs ok on your device. Also, by running the application once, your application "subscribes" to push notifications from your application on Parse. That will be crucial for the next step.
Testing Notifications at Parse
I recognize that screen shot has a lot of information on it, so let me quickly review it. You can see a list of all previously sent messages on top. Beneath it is a form to let you send messages. I mentioned above that applications can choose to subscribe to a particular channel. What channels you use are entirely dependent on your application. For now you will just ignore this and use the default Broadcast channel. In the Push Data box, keep the radio button at the default (Message) and enter something wise.
Hit the Send button and you should see - pretty darn immediately - the alert arrive on your device:
You can even close the application. If you send a new notification and select it in your Android... err.... whatever they call it (notification tray?) your application should open up.
Congratulations. You can now send notifications to your device.
Responding Intelligently to Notifications
So all of the above took me less than an hour. It was pretty cut and dry. But then I hit a pretty big roadblock. How could I make my application recognize when it was loaded via a notification and actually tell me what the notification was?
At this point I figured I was pretty much toast. I Googled a bit. Scratched my head. Pouted a bit too. Finally, I tried something new. In my getExtra call, I tried using what I had seen as a class related to Push Notifications:
All I do is run the has test followed by a get call. I take the data, JSON stringify it, and log it to my console.
And that's it. Obviously real code would parse this data and do, well, whatever you want with it. As should be clear from the Parse.com form, you can send more than simple messages. Complex structures of data can be sent to your listening devices. Again, the whole Push Notification feature as a whole is very powerful. I definitely encourage you to look at it yourself, and knowing that you can use it within PhoneGap as well just makes it even better.
If you have any questions, or suggestions for improvement, just leave a comment below.