3) Modify your **AndroidManifest.xml** and add the following **activity**, **receiver** and **service** tags to your **application** section. (See the Sample_AndroidManifest.xml file in the Example folder.)
4) Modify your **res/xml/config.xml** to include the following line in order to tell Cordova to include this plugin and where it can be found: (See the Sample_config.xml file in the Example folder)
5) Add the **PushNotification.js** script to your assets/www folder (or javascripts folder, wherever you want really) and reference it in your main index.html file. This file's usage is described in the **Plugin API** section below.
Add the **PushNotification.js** script to your assets/www folder (or javascripts folder, wherever you want really) and reference it in your main index.html file.
[TARGET-PATH] = path to folder containing your phonegap project
[PLUGIN-PATH] = path to folder containing this plugin
```
For additional info, take a look at the [Plugman Documentation](https://github.com/apache/cordova-plugman/blob/master/README.md)
@@ -124,11 +138,15 @@ In the Examples folder you will find a sample implementation showing how to inte
First create the plugin instance variable.
```js
varpushNotification;
```
When deviceReady fires, get the plugin reference
```js
pushNotification=window.plugins.pushNotification;
```
#### register
This should be called as soon as the device becomes ready. On success, you will get a call to tokenHandler (iOS), or onNotificationGCM (Android), allowing you to obtain the device token or registration ID, respectively. Those values will typically get posted to your intermediary push server so it knows who it can send notifications to.
@@ -138,55 +156,81 @@ For Android, If you have not already done so, you'll need to set up a Google API
In this example, be sure and substitute your own senderID. Get your senderID by signing into to your [google dashboard](https://code.google.com/apis/console/). The senderID is found at **Overview->Dashboard->Project Number**.
if (device.platform == 'android' || device.platform == 'Android') {
if (device.platform=='android'||device.platform=='Android')
{
pushNotification.register(
successHandler,
errorHandler,{
"senderID":"replace_with_sender_id",
"ecb":"onNotificationGCM"
});
}
else
{
pushNotification.register(
tokenHandler,
errorHandler,{
"badge":"true",
"sound":"true",
"alert":"true",
"ecb":"onNotificationAPN"
});
}
```
**successHandler** - called when a plugin method returns without error
```js
// result contains any message sent from the plugin call
functionsuccessHandler(result){
alert('result = '+result)
alert('result = '+result);
}
```
**errorHandler** - called when the plugin returns an error
```js
// result contains any error description text returned from the plugin call
functionerrorHandler(error){
alert('error = '+error)
alert('error = '+error);
}
```
**tokenHandler (iOS ony)** - called when the device has registeredwith a unique device token.
```js
functiontokenHandler(result){
// Your iOS push server needs to know the token before it can push to this device
// here is where you might want to send it the token for later use.
alert('device token = '+result)
alert('device token = '+result);
}
```
**senderID (Android only)** - This is the Google project ID you need to obtain by [registering your application](http://developer.android.com/guide/google/gcm/gs.html) for GCM
**ecb** - event callback that gets called when your device receives a notification
@@ -235,6 +283,7 @@ In this example, be sure and substitute your own senderID. Get your senderID by
break;
}
}
```
Looking at the above message handling code for Android, a few things bear explaination. Your app may receive a notification while it is active (INLINE). If you background the app by hitting the Home button on your device, you may later receive a status bar notification. Selecting that notification from the status will bring your app to the front and allow you to process the notification (BACKGROUND). Finally, should you completely exit the app by hitting the back button from the home page, you may still receive a notification. Touching that notification in the notification tray will relaunch your app and allow you to process the notification (COLDSTART). In this case the **coldstart** flag will be set on the incoming event. You can look at the **foreground** flag on the event to determine whether you are processing a background or an in-line notification. You may choose, for example to play a sound or show a dialog only for inline or coldstart notifications since the user has already been alerted via the status bar.
@@ -243,10 +292,13 @@ Also make note of the **payload** object. Since the Android notification data mo
#### unregister
You will typically call this when your app is exiting, to cleanup any used resources. Its not strictly necessary to call it, and indeed it may be desireable to NOT call it if you are debugging your intermediarry push server. When you call unregister(), the current token for a particular device will get invalidated, and the next call to register() will return a new token. If you do NOT call unregister(), the last token will remain in effect until it is invalidated for some reason at the GCM side. Since such invalidations are beyond your control, its recommended that, in a production environment, that you have a matching unregister() call, for every call to register(), and that your server updates the devices' records each time.
You'll probably want to trap on the **backbutton** event and only call this when the home page is showing. Remember, the back button on android is not the same as the Home button. When you hit the back button from the home page, your activity gets dismissed. Here is an example of how to trap the backbutton event;
