author | Matthew Wild <mwild1@gmail.com> |
Tue, 12 Mar 2024 14:27:43 +0000 | |
changeset 5869 | bfc35ae9edcb |
parent 5220 | 1d9dbe84b6e8 |
permissions | -rw-r--r-- |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
1 |
--- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
2 |
labels: |
2253
d3e697c141e4
mod_cloud_notify/README: Let's call it Beta
Kim Alvefur <zash@zash.se>
parents:
2252
diff
changeset
|
3 |
- 'Stage-Beta' |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
4 |
summary: 'XEP-0357: Cloud push notifications' |
2203
2582d09d2ec4
mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents:
2202
diff
changeset
|
5 |
--- |
1787
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
6 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
7 |
Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
8 |
============ |
1787
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
9 |
|
5062
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
10 |
This module enables support for sending "push notifications" to clients that |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
11 |
need it, typically those running on certain mobile devices. |
1787
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
12 |
|
5062
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
13 |
As well as this module, your client must support push notifications (the apps |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
14 |
that need it generally do, of course) and the app developer's push gateway |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
15 |
must be reachable from your Prosody server (this happens over a normal XMPP |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
16 |
server-to-server 's2s' connection). |
3093
5b5c6ba527fc
mod_cloud_notify: last cleanup
tmolitor <thilo@eightysoft.de>
parents:
3092
diff
changeset
|
17 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
18 |
Details |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1789
diff
changeset
|
19 |
======= |
1787
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
20 |
|
5062
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
21 |
Some platforms, notably Apple's iOS and many versions of Android, impose |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
22 |
limits that prevent applications from running or accessing the network in the |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
23 |
background. This makes it difficult or impossible for an XMPP application to |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
24 |
remain reliably connected to a server to receive messages. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
25 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
26 |
In order for messaging and other apps to receive notifications, the OS vendors |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
27 |
run proprietary servers that their OS maintains a permanent connection to in |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
28 |
the background. Then they provide APIs to application developers that allow |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
29 |
sending notifications to specific devices via those servers. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
30 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
31 |
When you connect to your server with an app that requires push notifications, |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
32 |
it will use this module to set up a "push registration". When you receive |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
33 |
a message but your device is not connected to the server, this module will |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
34 |
generate a notification and send it to the push gateway operated by your |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
35 |
application's developers). Their gateway will then connect to your device's |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
36 |
OS vendor and ask them to forward the notification to your device. When your |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
37 |
device receives the notification, it will display it or wake up the app so it |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
38 |
can connect to XMPP and receive any pending messages. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
39 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
40 |
This protocol is described for developers in [XEP-0357: Push Notifications]. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
41 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
42 |
For this module to work reliably, you must have [mod_smacks], [mod_mam] and |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
43 |
[mod_carbons] also enabled on your server. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
44 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
45 |
Some clients, notably Siskin and Snikket iOS need some additional extensions |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
46 |
that are not currently defined in a standard XEP. To support these clients, |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
47 |
see [mod_cloud_notify_extensions]. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
48 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
49 |
Configuration |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
50 |
============= |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
51 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
52 |
Option Default Description |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
53 |
------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
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 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
55 |
`push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
56 |
`push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
57 |
`push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
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. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
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. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
60 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
61 |
(\*) There are privacy implications for enabling these options. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
62 |
|
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
63 |
Internal design notes |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
64 |
===================== |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5060
diff
changeset
|
65 |
|
2613
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2399
diff
changeset
|
66 |
App servers are notified about offline messages, messages stored by [mod_mam] |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2399
diff
changeset
|
67 |
or messages waiting in the smacks queue. |
3092
6eaa1aa4f8ae
mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents:
3091
diff
changeset
|
68 |
The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. |
6eaa1aa4f8ae
mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents:
3091
diff
changeset
|
69 |
|
2399
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:
2254
diff
changeset
|
70 |
To cooperate with [mod_smacks] this module consumes some events: |
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
71 |
`smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. |
2399
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:
2254
diff
changeset
|
72 |
These events allow this module to send out notifications for messages received |
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:
2254
diff
changeset
|
73 |
while the session is hibernated by [mod_smacks] or even when smacks |
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:
2254
diff
changeset
|
74 |
acknowledgements for messages are delayed by a certain amount of seconds |
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
75 |
configurable with the [mod_smacks] setting `smacks_max_ack_delay`. |
2399
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:
2254
diff
changeset
|
76 |
|
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
77 |
The `smacks_max_ack_delay` setting allows to send out notifications to clients |
2399
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:
2254
diff
changeset
|
78 |
which aren't already in smacks hibernation state (because the read timeout or |
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
79 |
connection close didn't already happen) but also aren't responding to acknowledgement |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
80 |
request in a timely manner. This setting thus allows conversations to be smoother |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
81 |
under such circumstances. |
1787
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
82 |
|
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
83 |
The new event `cloud-notify-ping` can be used by any module to send out a cloud |
2613
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2399
diff
changeset
|
84 |
notification to either all registered endpoints for the given user or only the endpoints |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2399
diff
changeset
|
85 |
given in the event data. |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2399
diff
changeset
|
86 |
|
2980
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
87 |
The config setting `push_notification_important_body` can be used to specify an alternative |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
88 |
body text to send to the remote pubsub node if the stanza is encrypted or has a body. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
89 |
This way the real contents of the message aren't revealed to the push appserver but it |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
90 |
can still see that the push is important. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
91 |
This is used by Chatsecure on iOS to send out high priority pushes in those cases for example. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2615
diff
changeset
|
92 |
|
2252
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2203
diff
changeset
|
93 |
Compatibility |
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2203
diff
changeset
|
94 |
============= |
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2203
diff
changeset
|
95 |
|
5220
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5062
diff
changeset
|
96 |
**Note:** This module should be used with Lua 5.2 and higher. Using it with |
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5062
diff
changeset
|
97 |
Lua 5.1 may cause push notifications to not be sent to some clients. |
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5062
diff
changeset
|
98 |
|
3948
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
99 |
------ ----------------------------------------------------------------------------- |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
100 |
trunk Works |
4972
487f1eb829cf
mod_cloud_notify: Compat for prosody 0.12
tmolitor <thilo@eightysoft.de>
parents:
3948
diff
changeset
|
101 |
0.12 Works |
3948
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
102 |
0.11 Works |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
103 |
0.10 Works |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
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) |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
105 |
------ ----------------------------------------------------------------------------- |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3947
diff
changeset
|
106 |
|
2252
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2203
diff
changeset
|
107 |
|
3090
3e91eb1bdd84
mod_cloud_notify: Some readme cleanup
tmolitor <thilo@eightysoft.de>
parents:
3083
diff
changeset
|
108 |
[^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service |
3094
1d0925d008b2
mod_cloud_notify: fix link to business rules description
tmolitor <thilo@eightysoft.de>
parents:
3093
diff
changeset
|
109 |
[^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown) |