Issue #828: Android double on('notification') fired

docs/PAYLOAD.md

@@ -1,3 +1,4 @@
+- [Overview](#overview)
 - [Android Behaviour](#android-behaviour)
   - [Images](#images)
   - [Sound](#sound)
@@ -23,6 +24,37 @@
   - [Background Notifications](#background-notifications-2)
 
 
+# Overview
+
+The following flowchart attempts to give you a picture of what happens when a push message arrives on your device when you have an app using phonegap-plugin-push.
+
+![push-flowchart](https://cloud.githubusercontent.com/assets/353180/15752003/36b80afa-28ba-11e6-818b-c6f5f2966d8f.png)
+
+## Push message arrives with app in foreground
+
+- The push plugin receives the data from the remote push service and calls all of your `notification`  event handlers.
+- The message is *not* displayed in the devices notification center as that is not normal behaviour for Android or iOS.
+
+## Push message arrives with app in background
+
+- The push plugin receives the data from the remote push service and checks to see if there is a title or message in the data received. If there is then the message will be displayed in the devices notification center.
+- Then the push plugin checks to see if the app is running. If the user has killed the application then no further processing of the push data will occur.
+- If they app is running in the background the push plugin then checks to see if `content-available` exists in the push data.
+- If `content-available` is set to `1` then the plugin calls all of your `notification` event handlers.
+
+## User clicks on notification in notification center
+
+- The app starts.
+- Then the plugin calls all of your `notification` event handlers.
+
+> Note: if the push payload contained `content-available: 1` then your `notification` event handler has already been called. It is up to you to handle the double event.
+
+Some ways to handle this *double* event are:
+
+- don't include title/message in the push so it doesn't show up in the shader.
+- send two pushes, one to be processed in the background the other to show up in the shade.
+- include a unique ID in your push so you can check to see if you've already processed this event.
+
 # Android Behaviour
 
 ## Images