Mercurial > prosody-modules

annotate 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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
2 labels:
2249
d3e697c141e4 mod_cloud_notify/README: Let's call it Beta
Kim Alvefur <zash@zash.se>
parents: 2248
diff changeset
3 - 'Stage-Beta'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
4 summary: 'XEP-0357: Cloud push notifications'
2199
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
5 ---
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
8 ============
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
5058
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
diff changeset
11 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
12
5058
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
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: 5056
diff changeset
16 server-to-server 's2s' connection).
3089
5b5c6ba527fc mod_cloud_notify: last cleanup
tmolitor <thilo@eightysoft.de>
parents: 3088
diff changeset
17
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
18 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
19 =======
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
5058
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
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: 5056
diff changeset
24 remain reliably connected to a server to receive messages.
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
25
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
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: 5056
diff changeset
29 sending notifications to specific devices via those servers.
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
30
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
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: 5056
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: 5056
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: 5056
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: 5056
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: 5056
diff changeset
38 can connect to XMPP and receive any pending messages.
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
39
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
diff changeset
41
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
diff changeset
43 [mod_carbons] also enabled on your server.
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
44
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
diff changeset
47 see [mod_cloud_notify_extensions].
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
48
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
49 Configuration
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
50 =============
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
51
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
52 Option Default Description
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
53 ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
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: 5056
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: 5056
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: 5056
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: 5056
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: 5056
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: 5056
diff changeset
60
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
61 (\*) There are privacy implications for enabling these options.
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
62
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
63 Internal design notes
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
64 =====================
39c2824c2880 mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents: 5056
diff changeset
65
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
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: 2395
diff changeset
67 or messages waiting in the smacks queue.
3088
6eaa1aa4f8ae mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents: 3087
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: 3087
diff changeset
69
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
70 To cooperate with [mod_smacks] this module consumes some events:
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
71 `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`.
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
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: 2250
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: 2250
diff changeset
74 acknowledgements for messages are delayed by a certain amount of seconds
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
75 configurable with the [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
76
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
77 The `smacks_max_ack_delay` setting allows to send out notifications to clients
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
78 which aren't already in smacks hibernation state (because the read timeout or
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
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: 2611
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: 2611
diff changeset
81 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
82
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
83 The new event `cloud-notify-ping` can be used by any module to send out a cloud
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
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: 2395
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: 2395
diff changeset
86
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
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: 2611
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: 2611
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: 2611
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: 2611
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: 2611
diff changeset
92
2248
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
93 Compatibility
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
94 =============
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
95
3944
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
96 ------ -----------------------------------------------------------------------------
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
97 trunk Works
4968
487f1eb829cf mod_cloud_notify: Compat for prosody 0.12
tmolitor <thilo@eightysoft.de>
parents: 3944
diff changeset
98 0.12 Works
3944
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
99 0.11 Works
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
100 0.10 Works
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
101 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: 3943
diff changeset
102 ------ -----------------------------------------------------------------------------
7630d4ade7cd mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents: 3943
diff changeset
103
2248
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
104
3086
3e91eb1bdd84 mod_cloud_notify: Some readme cleanup
tmolitor <thilo@eightysoft.de>
parents: 3079
diff changeset
105 [^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service
3090
1d0925d008b2 mod_cloud_notify: fix link to business rules description
tmolitor <thilo@eightysoft.de>
parents: 3089
diff changeset
106 [^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown)