This module enables support for sending "push notifications" to clients that

need it, typically those running on certain mobile devices.

As well as this module, your client must support push notifications (the apps

that need it generally do, of course) and the app developer's push gateway

must be reachable from your Prosody server (this happens over a normal XMPP

server-to-server 's2s' connection).

Some platforms, notably Apple's iOS and many versions of Android, impose

limits that prevent applications from running or accessing the network in the

background. This makes it difficult or impossible for an XMPP application to

remain reliably connected to a server to receive messages.

In order for messaging and other apps to receive notifications, the OS vendors

run proprietary servers that their OS maintains a permanent connection to in

the background. Then they provide APIs to application developers that allow

sending notifications to specific devices via those servers.

When you connect to your server with an app that requires push notifications,

it will use this module to set up a "push registration". When you receive

a message but your device is not connected to the server, this module will

generate a notification and send it to the push gateway operated by your

application's developers). Their gateway will then connect to your device's

OS vendor and ask them to forward the notification to your device. When your

device receives the notification, it will display it or wake up the app so it

can connect to XMPP and receive any pending messages.

This protocol is described for developers in [XEP-0357: Push Notifications].

For this module to work reliably, you must have [mod_smacks], [mod_mam] and

[mod_carbons] also enabled on your server.

Some clients, notably Siskin and Snikket iOS need some additional extensions

that are not currently defined in a standard XEP. To support these clients,

see [mod_cloud_notify_extensions].

Configuration

=============

  Option                               Default           Description

  ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------

  `push_notification_important_body`   `New Message!`    The body text to use when the stanza is important (see above), no message body is sent if this is empty

  `push_max_errors`                    `16`              How much persistent push errors are tolerated before notifications for the identifier in question are disabled

  `push_max_devices`                   `5`               The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)

  `push_max_hibernation_timeout`       `259200` (72h)    Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours)

  `push_notification_with_body` (\*)   `false`           Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended.

  `push_notification_with_sender` (\*) `false`           Whether or not to send the real message sender to remote pubsub node.  Enabling this may expose your contacts to your client developers and OS vendor. Not recommended.

(\*) There are privacy implications for enabling these options.

Internal design notes

=====================