prosody-modules
342f88e8d522
mod_cloud_notify/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_cloud_notify/README.md @ 6309:342f88e8d522 draft

Merge update
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Sun, 15 Jun 2025 01:08:46 +0700
parent 6306:fe0a58b863db
comparison
equal deleted inserted replaced
6279:b92aea4e7ff4 6309:342f88e8d522
2 labels: 2 labels:
3 - 'Stage-Beta' 3 - 'Stage-Beta'
4 summary: 'XEP-0357: Cloud push notifications' 4 summary: 'XEP-0357: Cloud push notifications'
5 --- 5 ---
6 6
7 Introduction 7 # Introduction
8 ============
9 8
10 This module enables support for sending "push notifications" to clients that 9 This module enables support for sending "push notifications" to clients
11 need it, typically those running on certain mobile devices. 10 that need it, typically those running on certain mobile devices.
12 11
13 As well as this module, your client must support push notifications (the apps 12 As well as this module, your client must support push notifications (the
14 that need it generally do, of course) and the app developer's push gateway 13 apps that need it generally do, of course) and the app developer's push
15 must be reachable from your Prosody server (this happens over a normal XMPP 14 gateway must be reachable from your Prosody server (this happens over a
16 server-to-server 's2s' connection). 15 normal XMPP server-to-server 's2s' connection).
17 16
18 Details 17 # Details
19 =======
20 18
21 Some platforms, notably Apple's iOS and many versions of Android, impose 19 Some platforms, notably Apple's iOS and many versions of Android, impose
22 limits that prevent applications from running or accessing the network in the 20 limits that prevent applications from running or accessing the network
23 background. This makes it difficult or impossible for an XMPP application to 21 in the background. This makes it difficult or impossible for an XMPP
24 remain reliably connected to a server to receive messages. 22 application to remain reliably connected to a server to receive
23 messages.
25 24
26 In order for messaging and other apps to receive notifications, the OS vendors 25 In order for messaging and other apps to receive notifications, the OS
27 run proprietary servers that their OS maintains a permanent connection to in 26 vendors run proprietary servers that their OS maintains a permanent
28 the background. Then they provide APIs to application developers that allow 27 connection to in the background. Then they provide APIs to application
29 sending notifications to specific devices via those servers. 28 developers that allow sending notifications to specific devices via
29 those servers.
30 30
31 When you connect to your server with an app that requires push notifications, 31 When you connect to your server with an app that requires push
32 it will use this module to set up a "push registration". When you receive 32 notifications, it will use this module to set up a "push registration".
33 a message but your device is not connected to the server, this module will 33 When you receive a message but your device is not connected to the
34 generate a notification and send it to the push gateway operated by your 34 server, this module will generate a notification and send it to the push
35 application's developers). Their gateway will then connect to your device's 35 gateway operated by your application's developers). Their gateway will
36 OS vendor and ask them to forward the notification to your device. When your 36 then connect to your device's OS vendor and ask them to forward the
37 device receives the notification, it will display it or wake up the app so it 37 notification to your device. When your device receives the notification,
38 can connect to XMPP and receive any pending messages. 38 it will display it or wake up the app so it can connect to XMPP and
39 receive any pending messages.
39 40
40 This protocol is described for developers in [XEP-0357: Push Notifications]. 41 This protocol is described for developers in [XEP-0357: Push
42 Notifications].
41 43
42 For this module to work reliably, you must have [mod_smacks], [mod_mam] and 44 For this module to work reliably, you must have [mod_smacks],
43 [mod_carbons] also enabled on your server. 45 [mod_mam] and [mod_carbons] also enabled on your server.
44 46
45 Some clients, notably Siskin and Snikket iOS need some additional extensions 47 Some clients, notably Siskin and Snikket iOS need some additional
46 that are not currently defined in a standard XEP. To support these clients, 48 extensions that are not currently defined in a standard XEP. To support
47 see [mod_cloud_notify_extensions]. 49 these clients, see [mod_cloud_notify_extensions].
48 50
49 Configuration 51 # Configuration
50 =============
51 52
52 Option Default Description 53 Option Default Description
53 ------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- 54 -------------------------------------- ---------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
54 `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 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
55 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled 56 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled
56 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) 57 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
57 `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) 58 `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours)
58 `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. 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.
59 `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. 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.
60 61
61 (\*) There are privacy implications for enabling these options. 62 (\*) There are privacy implications for enabling these options.[^1]
62 63
63 Internal design notes 64 # Internal design notes
64 =====================
65 65
66 App servers are notified about offline messages, messages stored by [mod_mam] 66 App servers are notified about offline messages, messages stored by
67 or messages waiting in the smacks queue. 67 [mod_mam] or messages waiting in the smacks queue. The business rules
68 The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. 68 outlined
69 [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html)
70 are all honored[^2].
69 71
70 To cooperate with [mod_smacks] this module consumes some events: 72 To cooperate with [mod_smacks] this module consumes some events:
71 `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. 73 `smacks-ack-delayed`, `smacks-hibernation-start` and
72 These events allow this module to send out notifications for messages received 74 `smacks-hibernation-end`. These events allow this module to send out
73 while the session is hibernated by [mod_smacks] or even when smacks 75 notifications for messages received while the session is hibernated by
74 acknowledgements for messages are delayed by a certain amount of seconds 76 [mod_smacks] or even when smacks acknowledgements for messages are
75 configurable with the [mod_smacks] setting `smacks_max_ack_delay`. 77 delayed by a certain amount of seconds configurable with the
78 [mod_smacks] setting `smacks_max_ack_delay`.
76 79
77 The `smacks_max_ack_delay` setting allows to send out notifications to clients 80 The `smacks_max_ack_delay` setting allows to send out notifications to
78 which aren't already in smacks hibernation state (because the read timeout or 81 clients which aren't already in smacks hibernation state (because the
79 connection close didn't already happen) but also aren't responding to acknowledgement 82 read timeout or connection close didn't already happen) but also aren't
80 request in a timely manner. This setting thus allows conversations to be smoother 83 responding to acknowledgement request in a timely manner. This setting
81 under such circumstances. 84 thus allows conversations to be smoother under such circumstances.
82 85
83 The new event `cloud-notify-ping` can be used by any module to send out a cloud 86 The new event `cloud-notify-ping` can be used by any module to send out
84 notification to either all registered endpoints for the given user or only the endpoints 87 a cloud notification to either all registered endpoints for the given
85 given in the event data. 88 user or only the endpoints given in the event data.
86 89
87 The config setting `push_notification_important_body` can be used to specify an alternative 90 The config setting `push_notification_important_body` can be used to
88 body text to send to the remote pubsub node if the stanza is encrypted or has a body. 91 specify an alternative body text to send to the remote pubsub node if
89 This way the real contents of the message aren't revealed to the push appserver but it 92 the stanza is encrypted or has a body. This way the real contents of the
90 can still see that the push is important. 93 message aren't revealed to the push appserver but it can still see that
91 This is used by Chatsecure on iOS to send out high priority pushes in those cases for example. 94 the push is important. This is used by Chatsecure on iOS to send out
95 high priority pushes in those cases for example.
92 96
93 Compatibility 97 # Compatibility
94 =============
95 98
96 **Note:** This module should be used with Lua 5.2 and higher. Using it with 99 **Note:** This module should be used with Lua 5.2 and higher. Using it
97 Lua 5.1 may cause push notifications to not be sent to some clients. 100 with Lua 5.1 may cause push notifications to not be sent to some
101 clients.
98 102
99 ------ ----------------------------------------------------------------------------- 103 ------- ----------------------
100 trunk Works 104 trunk Works as of 25-06-13
101 0.12 Works 105 13.0 Works
102 0.11 Works 106 0.12 Works
103 0.10 Works 107 ------- ----------------------
104 0.9 Support dropped, use last supported version [675726ab06d3](//hg.prosody.im/prosody-modules/raw-file/675726ab06d3/mod_cloud_notify/mod_cloud_notify.lua)
105 ------ -----------------------------------------------------------------------------
106 108
109 [^1]: The service which is expected to forward notifications to
110 something like Google Cloud Messaging or Apple Notification Service
107 111
108 [^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service 112 [^2]: [business_rules.md](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.md)
109 [^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown)