Software / code / prosody-modules
Annotate
mod_cloud_notify/README.md @ 6322:dfc035ecabb4
mod_http_oauth2: Remove defaults that should be included on clients
Since create_client() adds these fields if they are missing, we can
assume that they are present.
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Thu, 03 Jul 2025 12:32:43 +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) |
