Software / code / prosody-modules
Annotate
mod_cloud_notify/README.md @ 6319:63ef69b2f046
mod_http_oauth2: Assume Prosody 13.0+ roles are available
Per the README, 0.12 is not supported, so we should not need to worry
about this. Plus it is assumed to be present elsewhere and that would
throw errors.
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Wed, 02 Jul 2025 16:15:32 +0200 |
| parent | 6306:fe0a58b863db |
| rev | line source |
|---|---|
|
6304
6c484931c547
mod_cloud_notify: Readme: labels, how hard can it be?
Menel <menel@snikket.de>
parents:
6303
diff
changeset
|
1 --- |
|
6303
d73cae8d80ce
mod_cloud_notify: actually fix labels
Menel <menel@snikket.de>
parents:
6302
diff
changeset
|
2 labels: |
|
d73cae8d80ce
mod_cloud_notify: actually fix labels
Menel <menel@snikket.de>
parents:
6302
diff
changeset
|
3 - 'Stage-Beta' |
|
d73cae8d80ce
mod_cloud_notify: actually fix labels
Menel <menel@snikket.de>
parents:
6302
diff
changeset
|
4 summary: 'XEP-0357: Cloud push notifications' |
|
6304
6c484931c547
mod_cloud_notify: Readme: labels, how hard can it be?
Menel <menel@snikket.de>
parents:
6303
diff
changeset
|
5 --- |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
6 |
| 6301 | 7 # Introduction |
|
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
8 |
| 6301 | 9 This module enables support for sending "push notifications" to clients |
| 10 that need it, typically those running on certain mobile devices. | |
|
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
11 |
| 6301 | 12 As well as this module, your client must support push notifications (the |
| 13 apps that need it generally do, of course) and the app developer's push | |
| 14 gateway must be reachable from your Prosody server (this happens over a | |
| 15 normal XMPP server-to-server 's2s' connection). | |
|
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
16 |
| 6301 | 17 # Details |
|
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
18 |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
19 Some platforms, notably Apple's iOS and many versions of Android, impose |
| 6301 | 20 limits that prevent applications from running or accessing the network |
| 21 in the background. This makes it difficult or impossible for an XMPP | |
| 22 application to remain reliably connected to a server to receive | |
| 23 messages. | |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
24 |
| 6301 | 25 In order for messaging and other apps to receive notifications, the OS |
| 26 vendors run proprietary servers that their OS maintains a permanent | |
| 27 connection to in the background. Then they provide APIs to application | |
| 28 developers that allow sending notifications to specific devices via | |
| 29 those servers. | |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
30 |
| 6301 | 31 When you connect to your server with an app that requires push |
| 32 notifications, it will use this module to set up a "push registration". | |
| 33 When you receive a message but your device is not connected to the | |
| 34 server, this module will generate a notification and send it to the push | |
| 35 gateway operated by your application's developers). Their gateway will | |
| 36 then connect to your device's OS vendor and ask them to forward the | |
| 37 notification to your device. When your device receives the notification, | |
| 38 it will display it or wake up the app so it can connect to XMPP and | |
| 39 receive any pending messages. | |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
40 |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
41 This protocol is described for developers in [XEP-0357: Push |
|
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
42 Notifications]. |
| 6301 | 43 |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
44 For this module to work reliably, you must have [mod_smacks], |
|
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
45 [mod_mam] and [mod_carbons] also enabled on your server. |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
46 |
| 6301 | 47 Some clients, notably Siskin and Snikket iOS need some additional |
| 48 extensions that are not currently defined in a standard XEP. To support | |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
49 these clients, see [mod_cloud_notify_extensions]. |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
50 |
| 6301 | 51 # Configuration |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
52 |
| 6301 | 53 Option Default Description |
| 54 -------------------------------------- ---------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 55 `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 | |
| 56 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled | |
| 57 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) | |
| 58 `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) | |
| 59 `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. | |
| 60 `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. | |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
61 |
| 6301 | 62 (\*) There are privacy implications for enabling these options.[^1] |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
63 |
| 6301 | 64 # Internal design notes |
|
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
65 |
| 6301 | 66 App servers are notified about offline messages, messages stored by |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
67 [mod_mam] or messages waiting in the smacks queue. The business rules |
| 6301 | 68 outlined |
| 69 [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) | |
| 70 are all honored[^2]. | |
|
3088
6eaa1aa4f8ae
mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents:
3087
diff
changeset
|
71 |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
72 To cooperate with [mod_smacks] this module consumes some events: |
| 6301 | 73 `smacks-ack-delayed`, `smacks-hibernation-start` and |
| 74 `smacks-hibernation-end`. These events allow this module to send out | |
| 75 notifications for messages received while the session is hibernated by | |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
76 [mod_smacks] or even when smacks acknowledgements for messages are |
| 6301 | 77 delayed by a certain amount of seconds configurable with the |
|
6302
06fbbd45ba75
mod_cloud_notify: Readme: fix links and labels that were removed in the last commit
Menel <menel@snikket.de>
parents:
6301
diff
changeset
|
78 [mod_smacks] setting `smacks_max_ack_delay`. |
|
2395
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
79 |
| 6301 | 80 The `smacks_max_ack_delay` setting allows to send out notifications to |
| 81 clients which aren't already in smacks hibernation state (because the | |
| 82 read timeout or connection close didn't already happen) but also aren't | |
| 83 responding to acknowledgement request in a timely manner. This setting | |
| 84 thus allows conversations to be smoother under such circumstances. | |
|
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
85 |
| 6301 | 86 The new event `cloud-notify-ping` can be used by any module to send out |
| 87 a cloud notification to either all registered endpoints for the given | |
| 88 user or only the endpoints given in the event data. | |
|
2609
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
89 |
| 6301 | 90 The config setting `push_notification_important_body` can be used to |
| 91 specify an alternative body text to send to the remote pubsub node if | |
| 92 the stanza is encrypted or has a body. This way the real contents of the | |
| 93 message aren't revealed to the push appserver but it can still see that | |
| 94 the push is important. This is used by Chatsecure on iOS to send out | |
| 95 high priority pushes in those cases for example. | |
|
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
96 |
| 6301 | 97 # Compatibility |
|
5216
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5058
diff
changeset
|
98 |
| 6301 | 99 **Note:** This module should be used with Lua 5.2 and higher. Using it |
| 100 with Lua 5.1 may cause push notifications to not be sent to some | |
| 101 clients. | |
|
3944
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
102 |
| 6306 | 103 ------- ---------------------- |
| 6301 | 104 trunk Works as of 25-06-13 |
| 6306 | 105 13.0 Works |
| 6301 | 106 0.12 Works |
| 6306 | 107 ------- ---------------------- |
|
2248
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2199
diff
changeset
|
108 |
| 6301 | 109 [^1]: The service which is expected to forward notifications to |
| 110 something like Google Cloud Messaging or Apple Notification Service | |
| 111 | |
| 112 [^2]: [business_rules.md](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.md) |
