Mercurial > prosody-modules

annotate mod_cloud_notify/README.markdown @ 3257:f09d92579158

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_atom: Add a brief README
author Kim Alvefur <zash@zash.se>
date Fri, 24 Aug 2018 16:16:30 +0200
parents 1d0925d008b2
children f5e6368a1c39
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
2250
f5cc6328b20f mod_cloud_notify/README: Reflow text
Kim Alvefur <zash@zash.se>
parents: 2249
diff changeset
10 This is an implementation of the server bits of [XEP-0357: Push Notifications].
f5cc6328b20f mod_cloud_notify/README: Reflow text
Kim Alvefur <zash@zash.se>
parents: 2249
diff changeset
11 It allows clients to register an "app server" which is notified about new
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
12 messages while the user is offline, disconnected or the session is hibernated
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
13 by [mod_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
14 Implementation of the "app server" is not included[^1].
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
3089
5b5c6ba527fc mod_cloud_notify: last cleanup
tmolitor <thilo@eightysoft.de>
parents: 3088
diff changeset
16 **Please note: Multi client setups don't work properly if MAM is disabled and using this module won't change this at all!**
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
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
21 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
22 or messages waiting in the smacks queue.
3088
6eaa1aa4f8ae mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents: 3087
diff changeset
23 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
24
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
25 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
26 `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
27 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
28 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
29 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
30 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
31
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
32 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
33 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
34 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
35 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
36 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
37
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
38 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
39 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
40 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
41
2976
df86ce6bb0b4 Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents: 2611
diff changeset
42 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
43 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
44 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
45 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
46 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
47
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
48 Configuration
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
49 =============
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
50
3055
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
51 Option Default Description
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
52 ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
53 `push_notification_with_body` `false` Whether or not to send the message body to remote pubsub node.
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
54 `push_notification_with_sender` `false` Whether or not to send the message sender to remote pubsub node.
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
55 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
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
6abee021d9db mod_cloud_notify: Limit number of devices to 5 and change some default settings
tmolitor <thilo@eightysoft.de>
parents: 2976
diff changeset
57 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
58
2199
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
59 There are privacy implications for enabling these options because
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
60 plaintext content and metadata will be shared with centralized servers
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
61 (the pubsub node) run by arbitrary app developers.
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
62
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
63 Installation
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
64 ============
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 Same as any other module.
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
68 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
69 =============
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 Configured in-band by supporting clients.
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72
2248
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
73 Compatibility
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
74 =============
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
75
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
76 Should work with 0.9+.
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
77
3086
3e91eb1bdd84 mod_cloud_notify: Some readme cleanup
tmolitor <thilo@eightysoft.de>
parents: 3079
diff changeset
78 [^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
79 [^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown)