Mercurial > prosody-modules

comparison mod_cloud_notify/README.markdown @ 5058:39c2824c2880

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_cloud_notify: README overhaul
author Matthew Wild <mwild1@gmail.com>
date Sat, 24 Sep 2022 09:25:46 +0100
parents 2583bd7eb5d1
children 1d9dbe84b6e8
comparison
equal deleted inserted replaced
5057:c728e82265a7 5058:39c2824c2880
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