Push Notifications documentation enhancement

CONTRIBUTING.md

@@ -38,11 +38,6 @@ appropriate for programmer's failures on the Dart side of things. But time will
 
 ### Push Notifications 
 
-#### Debugging the app from launch
-
-- Android: Go into developer options and use the "Wait for debugger" option. Launch the app from the Flutter project (not the `android` directory) in Android Studio. Then in the Android project in Android Studio, attach the debugger.
-- iOS: In Xcode, build the Xcode app scheme with launch option: "Wait for the executable to be launched" instead of "Automatically". You need to repeat this for every launch. Then "Attach Flutter" in Android Studio or CLI if you want to, as well. 
-
 #### Push Notifications activation / deactivation
 
 The platform SDKs ([ably-android](https://github.com/ably/ably-java), [ably-cocoa](https://github.com/ably/ably-cocoa)) provide ways to check if device activation, deactivation or registration update fails. On Android, these errors are sent in Intents which you should register for at runtime. In Cocoa, your errors are provided through `ARTPushRegistererDelegate` methods. However, this error does not get returned immediately/quickly in all cases. For example, if there was no internet connection, then `Push.activate()` will not throw an error, it will just block forever, because errors are not provided by the SDKs. Once an internet connection is made, the intent will be sent / delegate methods will be called.

PushNotifications.md

@@ -210,6 +210,12 @@ data: 'This is a Ably message published on channels that is also '
 }));
 ```
 
+#### Prioritising messages
+
+Only use high priority when it requires immediate user attention or interaction. Use the normal priority (5) otherwise. Messages with a high priority wake a device from a battery saving state, which drains the battery even more.
+- High priority: `'priority': 'high'` inside `push.fcm.android` for Android. `apns-priority: '10'` inside `push.apns.apns-headers` for iOS.
+- Normal priority:  `'priority': 'normal'` inside `push.fcm.android` for Android. `apns-priority: '5'` inside `push.apns.apns-headers` for iOS.
+
 #### Alert Notification **and** Background / Data Message
 
 Push notifications containing both the notification and data objects will be treated as both alert notifications and data messages.
@@ -309,7 +315,7 @@ ably.Push.notificationEvents.setOnBackgroundMessage(_backgroundMessageHandler);
 ```
   - This method can be synchronous or `async`.
 
-##### Advanced: native message handling
+#### Advanced: native message handling
 
 Users can listen to messages in each platform using the native message listeners instead of listening to messages on the Dart side. This is not recommended unless you want to **avoid** using other plugins, such as [awesome_notifications](https://pub.dev/packages/awesome_notifications) and [flutter_local_notifications](https://pub.dev/packages/flutter_local_notifications).
 
@@ -326,6 +332,12 @@ Users can listen to messages in each platform using the native message listeners
 
 Take a look at the example app platform specific code to handle messages. For iOS, this is `AppDelegate.m`, and in Android, it is `PushMessagingService.java`. For further help on implementing the Platform specific message handlers, see "On Android" and "On iOS" sections on [Push Notifications - Device activation and subscription](https://ably.com/documentation/general/push/activate-subscribe).
 
+### Additional considerations and resources
+- For tips on how best to use push messaging on Android, read [Notifying your users with FCM](https://android-developers.googleblog.com/2018/09/notifying-your-users-with-fcm.html). For example:
+  - Show a notification to the user as soon as possible without any additional data usage or processing. Perform additional synchronization work asynchronously after that, using [workmanager](https://pub.dev/packages/workmanager). You can also update the notification with a nicer notification, such as with buttons.
+  - Avoid background services: As recommended by FCM, Ably Flutter does not instantiate any background services or schedule any jobs on your behalf. Libraries and applications which do this, for example Firebase Messaging may face `IllegalStateException` exceptions and reduced execution time.
+- For more Android tips, read [About FCM messages](https://firebase.google.com/docs/cloud-messaging/concept-options)
+
 ### Deactivating the device
 
 Do this only if you do not want the device to receive push notifications at all. You usually do not need to run this at all. 
@@ -338,6 +350,18 @@ Do this only if you do not want the device to receive push notifications at all.
     }
 ```
 
+## Debugging applications from launch
+
+You may want to validate or debug situations where your application is terminated, in the background or in the foreground. 
+
+- Android: Go into developer options and use the "Wait for debugger" option. Launch the app from the Flutter project (not `android` directory) in Android Studio. This ensures any `--dart-define` variables are used by the application. Then in the Android project in Android Studio, attach the debugger. This allows you to debug Java code, such as the message handlers. Then "Attach Flutter" in Android Studio or CLI if you want to, as well. 
+
+![Developer options showing "Wait for debugger" option](images/android-developer-options-debugger.png)
+
+- iOS: In Xcode, configure your Xcode app scheme's **launch option** to "Wait for the executable to be launched" instead of "Automatically". Then "Attach Flutter" in Android Studio or CLI if you want to, as well. 
+
+![Xcode project scheme showing "Wait for the executable to be launched" selected](images/ios-xcode-scheme.png)
+
 ## Troubleshooting/ FAQ
 
 ### Push messages are not being delivered to my device.