wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clarifications to the push module (#2634)

Browse source 
* Minor clarifications to the push spec
* move conditions before defaults
This commit is contained in:
Richard van der Hoff 2020-06-16 16:56:31 +01:00 • committed by GitHub
parent f1e3118317
commit 5cb4b086c7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 62 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2634.clarification Normal file
View file

@ -0,0 +1 @@
Minor clarifications to the "Push Notifications" module.

118
specification/modules/push.rst
View file

@ -135,8 +135,9 @@ There are different "kinds" of push rules and each rule has an associated
priority. Every push rule MUST have a ``kind`` and ``rule_id``. The ``rule_id``
is a unique string within the kind of rule and its' scope: ``rule_ids`` do not
need to be unique between rules of the same kind on different devices. Rules may
have extra keys depending on the value of ``kind``. The different kinds of rule
in descending order of priority are:
have extra keys depending on the value of ``kind``.
The different ``kind``\ s of rule, in the order that they are checked, are:
Override Rules ``override``
The highest priority rules are user-configured overrides.
@ -156,15 +157,6 @@ Underride rules ``underride``
These are identical to ``override`` rules, but have a lower priority than
``content``, ``room`` and ``sender`` rules.
This means that the full list of rule kinds, in descending priority order, is
as follows:
* Global Override
* Global Content
* Global Room
* Global Sender
* Global Underride
Rules with the same ``kind`` can specify an ordering priority. This determines
which rule is selected in the event of multiple matches. For example, a rule
matching "tea" and a separate rule matching "time" would both match the sentence
@ -224,6 +216,55 @@ Tweaks are passed transparently through the homeserver so client applications
and Push Gateways may agree on additional tweaks. For example, a tweak may be
added to specify how to flash the notification light on a mobile device.
Conditions
++++++++++
``override`` and ``underride`` rules MAY have a list of 'conditions'.
All conditions must hold true for an event in order for the rule to match.
A rule with no conditions always matches. The following conditions are defined:
``event_match``
This is a glob pattern match on a field of the event. Parameters:
* ``key``: The dot-separated field of the event to match, e.g. ``content.body``
* ``pattern``: The glob-style pattern to match against. Patterns with no
special glob characters should be treated as having asterisks
prepended and appended when testing the condition.
``contains_display_name``
This matches unencrypted messages where ``content.body`` contains the owner's
display name in that room. This is a separate rule because display names may
change and as such it would be hard to maintain a rule that matched the user's
display name. This condition has no parameters.
``room_member_count``
This matches the current number of members in the room. Parameters:
* ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
count is strictly less than the given number and so forth. If no prefix is
present, this parameter defaults to ``==``.
``sender_notification_permission``
This takes into account the current power levels in the room, ensuring the
sender of the event has high enough power to trigger the notification.
Parameters:
* ``key``: A string that determines the power level the sender must have to trigger
notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_
event schema for information about what the defaults are and how to interpret the event.
The ``key`` is used to look up the power level required to send a notification type
from the ``notifications`` object in the power level event content.
Unrecognised conditions MUST NOT match any events, effectively making the push
rule disabled.
``room``, ``sender`` and ``content`` rules do not have conditions in the same
way, but instead have predefined conditions. In the cases of ``room`` and
``sender`` rules, the ``rule_id`` of the rule determines its behaviour.
Predefined Rules
++++++++++++++++
Homeservers can specify "server-default rules" which operate at a lower priority
@ -237,7 +278,7 @@ Default Override Rules
``.m.rule.master``
``````````````````
Matches all events, this can be enabled to turn off all push notifications
Matches all events. This can be enabled to turn off all push notifications
other than those generated by override rules set by the user. By default this
rule is disabled.
@ -257,9 +298,7 @@ Definition
``.m.rule.suppress_notices``
````````````````````````````
Matches messages with a ``msgtype`` of ``notice``. This should be an
``override`` rule so that it takes priority over ``content`` / ``sender`` /
``room`` rules.
Matches messages with a ``msgtype`` of ``notice``.
Definition:
@ -650,55 +689,6 @@ Definition:
]
}
Conditions
++++++++++
Override, Underride and Default Rules MAY have a list of 'conditions'.
All conditions must hold true for an event in order to apply the ``action`` for
the event. A rule with no conditions always matches. Room, Sender, User and
Content rules do not have conditions in the same way, but instead have
predefined conditions. These conditions can be configured using the parameters
outlined below. In the cases of room and sender rules, the ``rule_id`` of the
rule determines its behaviour. The following conditions are defined:
``event_match``
This is a glob pattern match on a field of the event. Parameters:
* ``key``: The dot-separated field of the event to match, e.g. ``content.body``
* ``pattern``: The glob-style pattern to match against. Patterns with no
special glob characters should be treated as having asterisks
prepended and appended when testing the condition.
``contains_display_name``
This matches unencrypted messages where ``content.body`` contains the owner's
display name in that room. This is a separate rule because display names may
change and as such it would be hard to maintain a rule that matched the user's
display name. This condition has no parameters.
``room_member_count``
This matches the current number of members in the room. Parameters:
* ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
count is strictly less than the given number and so forth. If no prefix is
present, this parameter defaults to ``==``.
``sender_notification_permission``
This takes into account the current power levels in the room, ensuring the
sender of the event has high enough power to trigger the notification.
Parameters:
* ``key``: A string that determines the power level the sender must have to trigger
notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_
event schema for information about what the defaults are and how to interpret the event.
The ``key`` is used to look up the power level required to send a notification type
from the ``notifications`` object in the power level event content.
Unrecognised conditions MUST NOT match any events, effectively making the push
rule disabled.
Push Rules: API
~~~~~~~~~~~~~~~