5 --- |
5 --- |
6 |
6 |
7 Introduction |
7 Introduction |
8 ============ |
8 ============ |
9 |
9 |
10 This is an implementation of the server bits of [XEP-0357: Push Notifications]. |
10 This module enables support for sending "push notifications" to clients that |
11 It allows clients to register an "app server" which is notified about new |
11 need it, typically those running on certain mobile devices. |
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 |
12 |
16 **Please note: Multi client setups don't work properly if MAM is disabled and using this module won't change this at all!** |
13 As well as this module, your client must support push notifications (the apps |
|
14 that need it generally do, of course) and the app developer's push gateway |
|
15 must be reachable from your Prosody server (this happens over a normal XMPP |
|
16 server-to-server 's2s' connection). |
17 |
17 |
18 Details |
18 Details |
19 ======= |
19 ======= |
|
20 |
|
21 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 |
|
23 background. This makes it difficult or impossible for an XMPP application to |
|
24 remain reliably connected to a server to receive messages. |
|
25 |
|
26 In order for messaging and other apps to receive notifications, the OS vendors |
|
27 run proprietary servers that their OS maintains a permanent connection to in |
|
28 the background. Then they provide APIs to application developers that allow |
|
29 sending notifications to specific devices via those servers. |
|
30 |
|
31 When you connect to your server with an app that requires push notifications, |
|
32 it will use this module to set up a "push registration". When you receive |
|
33 a message but your device is not connected to the server, this module will |
|
34 generate a notification and send it to the push gateway operated by your |
|
35 application's developers). Their gateway will then connect to your device's |
|
36 OS vendor and ask them to forward the notification to your device. When your |
|
37 device receives the notification, it will display it or wake up the app so it |
|
38 can connect to XMPP and receive any pending messages. |
|
39 |
|
40 This protocol is described for developers in [XEP-0357: Push Notifications]. |
|
41 |
|
42 For this module to work reliably, you must have [mod_smacks], [mod_mam] and |
|
43 [mod_carbons] also enabled on your server. |
|
44 |
|
45 Some clients, notably Siskin and Snikket iOS need some additional extensions |
|
46 that are not currently defined in a standard XEP. To support these clients, |
|
47 see [mod_cloud_notify_extensions]. |
|
48 |
|
49 Configuration |
|
50 ============= |
|
51 |
|
52 Option Default Description |
|
53 ------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- |
|
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_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_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_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 (\*) There are privacy implications for enabling these options. |
|
62 |
|
63 Internal design notes |
|
64 ===================== |
20 |
65 |
21 App servers are notified about offline messages, messages stored by [mod_mam] |
66 App servers are notified about offline messages, messages stored by [mod_mam] |
22 or messages waiting in the smacks queue. |
67 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]. |
68 The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. |
24 |
69 |
43 body text to send to the remote pubsub node if the stanza is encrypted or has a body. |
88 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 |
89 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. |
90 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. |
91 This is used by Chatsecure on iOS to send out high priority pushes in those cases for example. |
47 |
92 |
48 Configuration |
|
49 ============= |
|
50 |
|
51 Option Default Description |
|
52 ------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- |
|
53 `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. |
|
54 `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. |
|
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 `push_max_hibernation_timeout` `6220800` Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) |
|
59 |
|
60 There are privacy implications for enabling these options because |
|
61 plaintext content and metadata will be shared with centralized servers |
|
62 (the pubsub node) run by arbitrary app developers. |
|
63 |
|
64 Installation |
|
65 ============ |
|
66 |
|
67 Same as any other module. |
|
68 |
|
69 Configuration |
|
70 ============= |
|
71 |
|
72 Configured in-band by supporting clients. |
|
73 |
|
74 Compatibility |
93 Compatibility |
75 ============= |
94 ============= |
76 |
95 |
77 ------ ----------------------------------------------------------------------------- |
96 ------ ----------------------------------------------------------------------------- |
78 trunk Works |
97 trunk Works |