mod_cloud_notify/README.markdown

   1 ---
   2 labels:
   3 - 'Stage-Beta'
   4 summary: 'XEP-0357: Cloud push notifications'
   5 ---
   6
   7 Introduction
   8 ============
   9
  10 This is an implementation of the server bits of [XEP-0357: Push Notifications].
  11 It allows clients to register an "app server" which is notified about new
  12 messages while the user is offline, disconnected or the session is hibernated
  13 by [mod_smacks].
  14 Implementation of the "app server" is not included[^1].
  15
  16 **Please note: Multi client setups don't work properly if MAM is disabled and using this module won't change this at all!**
  17
  18 Details
  19 =======
  20
  21 App servers are notified about offline messages, messages stored by [mod_mam]
  22 or messages waiting in the smacks queue.
  23 The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2].
  24
  25 To cooperate with [mod_smacks] this module consumes some events:
  26 `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`.
  27 These events allow this module to send out notifications for messages received
  28 while the session is hibernated by [mod_smacks] or even when smacks
  29 acknowledgements for messages are delayed by a certain amount of seconds
  30 configurable with the [mod_smacks] setting `smacks_max_ack_delay`.
  31
  32 The `smacks_max_ack_delay` setting allows to send out notifications to clients
  33 which aren't already in smacks hibernation state (because the read timeout or
  34 connection close didn't already happen) but also aren't responding to acknowledgement
  35 request in a timely manner. This setting thus allows conversations to be smoother
  36 under such circumstances.
  37
  38 The new event `cloud-notify-ping` can be used by any module to send out a cloud
  39 notification to either all registered endpoints for the given user or only the endpoints
  40 given in the event data.
  41
  42 The config setting `push_notification_important_body` can be used to specify an alternative
  43 body text to send to the remote pubsub node if the stanza is encrypted or has a body.
  44 This way the real contents of the message aren't revealed to the push appserver but it
  45 can still see that the push is important.
  46 This is used by Chatsecure on iOS to send out high priority pushes in those cases for example.
  47
  48 Configuration
  49 =============
  50
  51   Option                               Default           Description
  52   ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
  53   `push_notification_with_body`        `false`           Whether or not to send the message body to remote pubsub node.
  54   `push_notification_with_sender`      `false`           Whether or not to send the message sender to remote pubsub node.
  55   `push_max_errors`                    `16`              How much persistent push errors are tolerated before notifications for the identifier in question are disabled
  56   `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
  57   `push_max_devices`                   `5`               The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
  58
  59 There are privacy implications for enabling these options because
  60 plaintext content and metadata will be shared with centralized servers
  61 (the pubsub node) run by arbitrary app developers.
  62
  63 Installation
  64 ============
  65
  66 Same as any other module.
  67
  68 Configuration
  69 =============
  70
  71 Configured in-band by supporting clients.
  72
  73 Compatibility
  74 =============
  75
  76 Should work with 0.9+.
  77
  78 [^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service
  79 [^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown)