### 推送通知

```
                                   +--------------------+  +-------------------+
                  Matrix HTTP      |                    |  |                   |
             Notification Protocol |   应用开发者        |  |   设备厂商         |
                                   |                    |  |                   |
           +-------------------+   | +----------------+ |  | +---------------+ |
           |                   |   | |                | |  | |               | |
           | Matrix 主服务器   +-----> 推送网关(Gateway)+------> 推送供应商      | |
           |                   |   | |                | |  | |               | |
           +-^-----------------+   | +----------------+ |  | +----+----------+ |
             |                     |                    |  |      |            |
    Matrix   |                     |                    |  |      |            |
 客户端/服务器API +                |                    |  |      |            |
             |      |              +--------------------+  +-------------------+
             |   +--+-+                                           |
             |   |    <-------------------------------------------+
             +---+    |
                 |    |          供应商推送协议
                 +----+
          移动设备或客户端
```

本模块增加了对推送通知的支持。主服务器会将事件的通知发送到用户配置的 HTTP 端点。用户也可以自定义多条规则，决定哪些事件会生成通知。这些规则全部存储并由用户的主服务器管理。这允许用户专属的推送设置在不同客户端应用之间复用。

上述图示显示了推送通知发送到手机时的流程，通知通过手机厂商（例如 Apple 的 APNS 或 Google 的 GCM）进行提交。具体流程如下：

1.  客户端应用登录到主服务器。
2.  客户端应用在其厂商的推送供应商处注册，并获得某种路由令牌。
3.  移动应用通过客户端/服务器 API 添加一个“推送者（pusher）”，并提供为该应用配置的特定推送网关的 URL，同时提供从推送供应商获得的路由令牌。
4.  主服务器使用提供的 URL 向推送网关发送 HTTP 请求。推送网关将该通知中继给推送供应商，并附带发送推送通知所需的路由令牌及相关私密凭证。
5.  推送供应商将通知发送至设备。

本节相关术语定义如下：

推送供应商（Push Provider）

:   推送供应商是由设备厂商管理的服务，可以直接将通知发送到设备。例如 Google Cloud Messaging（GCM）和 Apple Push Notification Service（APNS）都是推送供应商的例子。

推送网关（Push Gateway）

:   推送网关是接收主服务器 HTTP 事件通知并将其转发给其他协议（如 iOS 设备的 APNS 或 Android 设备的 GCM）的服务器。客户端在设置 Pusher 时，会告知主服务器该将通知发送至哪个推送网关。

推送者（Pusher）

:   Pusher 是主服务器上负责管理并发送 HTTP 通知给用户的工作进程。每个用户可以有多个 pusher，每组装置对应一个。

推送规则（Push Rule）

:   推送规则是一条声明了在什么*条件*下事件会被发送到推送网关，以及通知应该如何呈现的规则。这些规则储存在用户的主服务器上。用户可通过客户端/服务器 API 手动配置、创建与查看这些规则。

推送规则集（Push Ruleset）

:   推送规则集*根据某些标准限定某组规则的作用范围*。比如，某些规则只针对来自特定发信人的消息、特定聊天室、或作为默认规则。推送规则集包含了全部作用域与规则集合。

#### 推送规则

推送规则是一条声明了在什么*条件*下事件会被发送到推送网关，以及通知该如何呈现的规则。推送规则有多种“类型（kind）”，每条规则都有相应的优先级。每条推送规则必须包含 `kind` 和 `rule_id`。`rule_id` 是在该类型和作用域内部唯一的字符串：同种类型但属于不同设备的规则之间，`rule_id` 并不要求全局唯一。依据 `kind` 类型，规则可以具有额外的键。

不同的 `kind` 类型按如下顺序检查：

1.  **Override 规则 (`override`)。**
    最高优先级的规则，由用户配置作为覆盖项。

2.  **内容专属规则 (`content`)。**
    针对匹配某些模式的消息配置行为。内容规则包含一个参数 —— `pattern`，提供待匹配的[glob 风格模式](/appendices#glob-style-matching)。
    该匹配大小写不敏感，必须匹配消息内容的 `content.body` 属性中任何以单词边界起止的子串。单词边界指文本的起始或结尾，或者非 `[A-Z]`, `[a-z]`, `[0-9]`, `_` 集合中的任意字符。大小写不敏感的具体实现由主服务器定义。

3.  **房间专属规则 (`room`)。**
    更改某个房间内所有消息的通知行为。房间规则的 `rule_id` 总为其作用房间的 ID。

4.  **发信人专属规则 (`sender`)。**
    针对某个 Matrix 用户 ID 发出的消息配置通知行为。发信人规则的 `rule_id` 总为该用户的 Matrix ID。

5.  **Underride 规则 (`underride`)。**
    与 `override` 规则作用相同，但其优先级低于 `content`、`room` 和 `sender` 规则。

同一 `kind` 的规则可以指定顺序优先级，用于确定在多条规则命中时选择哪一条。例如，规则 A 匹配“tea”，规则 B 匹配“time”，则消息 “It's time for tea” 会被两条规则匹配，随后按顺序决定实际生效的规则。只有优先级最高的规则的 `actions` 会被发送给推送网关。

每条规则可以启用或禁用。被禁用的规则永不匹配。如果没有任何规则匹配某事件，主服务器不得为该事件通知推送网关。主服务器也不得为用户自己发送的事件通知推送网关。

##### 动作（Actions）

所有规则都有一个关联的 `actions` 动作列表。动作决定对于匹配的事件，通知是否被送达及如何送达。定义如下：

`notify`

:   为每个匹配事件产生推送通知。

`set_tweak`

:   设置发送通知请求给推送网关时 `tweaks` 字典键中的一项。格式为字典对象，`set_tweak` 为要设置的调整项名，如果需要还可带有 `value` 指定其值。

    已定义以下调整项：

    `sound`

    :   字符串，表示此通知到达时播放的声音。`default` 表示播放默认提示音。设备也可根据实际选择如振动等其他告警方式。

    `highlight`

    :   布尔值，是否应在界面中高亮展示这条消息。通常会以不同颜色/样式突出消息，或调整 UI 以特别提示发生消息的房间。如果给定了没有显式值的 `highlight` 调整项，其值视为 `true`。若未指定则为 `false`。

    调整项会透明地通过主服务器传递，客户端应用与推送网关可约定自定义调整项。例如，可指定在移动设备上如何闪烁通知灯。

无参数的动作用字符串表示，否则用以动作名为键、相关参数为其他键的字典表示，例如：`{ "set_tweak": "sound", "value": "default" }`。

###### 历史动作说明

早期 Matrix 规范包含 `dont_notify` 和 `coalesce` 动作。客户端和主服务器必须忽略这些动作，比如遇到时应从动作数组中剔除。因此，包含 `["dont_notify"]` 的规则应等效于动作数组为空的规则。

##### 条件（Conditions）

`override` 和 `underride` 规则可以有“条件”列表。事件必须满足所有条件，该规则才会匹配。若规则无任何条件，则总是匹配。

无法识别的条件不得匹配任何事件，相当于禁用该规则。

`room`、`sender` 和 `content` 规则不以条件列表的方式定义，而是有预定义条件。房间和发信人规则中，`rule_id` 的内容决定其行为。

以下条件类型已定义：

**`event_match`**

对事件某属性用 glob 模式匹配。参数：

-   `key`：事件属性的[点分路径](/appendices#dot-separated-property-paths)，如 `content.body`。
-   `pattern`：[glob 风格模式](/appendices#glob-style-matching)。

匹配大小写不敏感，必须匹配 `key` 指定属性的整个值（但 `content.body` 见下文）。大小写不敏感的实现由主服务器定义。

如事件中 `key` 指定属性完全不存在或不是字符串，即便 `pattern` 是 `*`，条件也不匹配。

{{% boxes/note %}}
例如，若 `key` 为 `content.topic`，`pattern` 为 `lunc?*`，其事件如下将会匹配：

```json
{
  "content": {
    "topic": "Lunch plans",
  },
  "event_id": "$143273582443PhrSn:example.org",
  "room_id": "!636q39766251:example.com",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.topic"
}
```

其它能匹配的 `topic` 值有：

 * `"LUNCH"`（大小写不敏感，`*` 可匹配零个字符）

以下 `topic` 不匹配：
 * `" lunch"`（前导空格）
 * `"lunc"`（`?` 必须匹配一个字符）
 * `null`（不是字符串）
{{% /boxes/note %}}

特殊情况：若 `key` 为 `content.body`，`pattern` 必须匹配属性值任一单词边界起止的子串。单词边界指值的起止或非 `[A-Z]`、`[a-z]`、`[0-9]`、`_` 集合的字符。

{{% boxes/note %}}
例如，`key` 若为 `content.body`，`pattern` 为 `ex*ple`，则如下消息会匹配：

```json
{
  "content": {
    "body": "An example event."
  },
  "event_id": "$143273976499sgjks:example.org",
  "room_id": "!636q39766251:example.com",
  "sender": "@example:example.org",
  "type": "m.room.message"
}
```

其它匹配 `body` 值有：

 * `"exple"`（模式可匹配 body 起止）
 * `"An exciting triple-whammy"`（模式可跨多单词，且 `-` 被视为分隔符）
{{% /boxes/note %}}


{{% boxes/warning %}}
注意，`state_key` 没有默认隐式条件。即，针对只匹配状态事件的推送规则，必须明确指定对 `state_key` 的条件。

例如，见下方默认规则
[`.m.rule.tombstone`](#mruletombstone)。
{{% /boxes/warning %}}

**`event_property_is`**

对事件属性值进行精确匹配。参数：

-   `key`：事件属性的[点分路径](/appendices#dot-separated-property-paths)，如 `content.body`。
-   `value`：要匹配的值。

匹配为精确等值，仅支持非复合（canonical JSON）类型：字符串、区间 `[-(2**53)+1, (2**53)-1]` 内的整数、布尔值和 `null`。

如 `key` 指定属性不存在，或类型不是字符串、整数、布尔或 `null`，条件不匹配。

{{% boxes/note %}}
例如，若 `key` 为 `content.m\.federate`，`value` 为 `true`，事件如下匹配：

```json
{
  "content": {
    "creator": "@example:example.org",
    "m.federate": true,
    "predecessor": {
      "event_id": "$something:example.org",
      "room_id": "!oldroom:example.org"
    },
    "room_version": "1"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "room_id": "!636q39766251:example.com",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.create"
}
```

下列 `m.federate` 值不匹配：
 * `"true"`（类型不同，字符串）
 * `1`（不进行类型转换）
{{% /boxes/note %}}

**`event_property_contains`**

如事件某数组属性*精确包含*特定值则匹配。参数：

-   `key`：事件属性的[点分路径](/appendices#dot-separated-property-paths)，如 `content.body`。

-   `value`：要匹配的值。

仅当数组元素为非复合 canonical JSON 类型（字符串、上述区间内整数、布尔、`null`）时有效。其他类型将被忽略。

如 `key` 指定属性不存在，或不是数组，则条件不匹配。

{{% boxes/note %}}
例如，若 `key` 为 `content.alt_aliases`，`value` 为 `"#myroom:example.com"`，如下事件会匹配：

```json
{
  "content": {
    "alias": "#somewhere:localhost",
    "alt_aliases": [
      "#somewhere:example.org",
      "#myroom:example.com"
    ]
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.canonical_alias",
  "unsigned": {
    "age": 1234
  }
}
```

下列 `alt_aliases` 值不匹配：
 * `":example.com"`（部分匹配不通过）
{{% /boxes/note %}}

**`contains_display_name`**

匹配 `content.body` 含有房间内该用户当前显示昵称的消息。因显示昵称可能变化，维护对应规则较难，故单独为此设一条件。该条件无参数。

**`room_member_count`**

匹配房间当前成员数。参数：

-   `is`：一个支持可选前缀的十进制整数，前缀包括 `==`、`<`、`>`、`>=` 或 `<=` 。如 `<` 匹配成员数*小于*给定数字，依此类推。缺省无前缀时为 `==`。

**`sender_notification_permission`**

结合房内当前权限设置，确保事件发送者权限足够以触发通知。

参数：

-   `key`：字符串，指定需触发何种类型通知时发信人需具备的权限级别，如 `room`。详见
    [m.room.power\_levels](#mroompower_levels) 事件结构。该 `key` 用于根据 power level 对象内容查找通知类型对应权限级别。

#### 预定义规则

主服务器可指定“服务器默认规则”。该类规则优先级低于“用户自定义规则”，唯一例外是 `.m.rule.master`，它总是所有规则中最高的。所有服务器默认规则的 `rule_id` 必须以点（"."）开头以便区分。以下为规定的服务器默认规则：

##### 默认 Override 规则

**`.m.rule.master`**

匹配所有事件。启用后可关闭所有推送通知。不同于其它服务器默认规则，此规则始终优先级最高，连用户自定义规则都排在其后。默认禁用。

定义：

```json
{
    "rule_id": ".m.rule.master",
    "default": true,
    "enabled": false,
    "conditions": [],
    "actions": []
}
```

**`.m.rule.suppress_notices`**

匹配 `msgtype` 为 `notice` 的消息。

定义：

```json
{
    "rule_id": ".m.rule.suppress_notices",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "content.msgtype",
            "pattern": "m.notice"
        }
    ],
    "actions": []
}
```

**`.m.rule.invite_for_me`**

匹配针对该用户的新房间邀请。

定义：

```json
{
    "rule_id": ".m.rule.invite_for_me",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
        },
        {
            "key": "content.membership",
            "kind": "event_match",
            "pattern": "invite"
        },
        {
            "key": "state_key",
            "kind": "event_match",
            "pattern": "[the user's Matrix ID]"
        }
    ],
    "actions": [
       "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}
```

**`.m.rule.member_event`**

匹配任意 `m.room.member_event`。

定义：

```json
{
    "rule_id": ".m.rule.member_event",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
        }
    ],
    "actions": []
}
```

<a id="_m_rule_is_user_mention"></a> **`.m.rule.is_user_mention`**

{{% added-in v="1.7" %}}

匹配在 `m.mentions` 属性下 `user_ids` 包含用户 Matrix ID 的任意消息。

定义：

```json
{
    "rule_id": ".m.rule.is_user_mention",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_property_contains",
            "key": "content.m\\.mentions.user_ids",
            "value": "[the user's Matrix ID]"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        },
        {
            "set_tweak": "highlight"
        }
    ]
}
```

<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**

{{% changed-in v="1.7" %}}

自 `v1.7` 起，该规则已废弃，**仅在事件未含 [`m.mentions` 属性](#definition-mmentions) 时启用**。

匹配内容含有用户当前房间显示昵称的消息。

定义：

```json
{
    "rule_id": ".m.rule.contains_display_name",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "contains_display_name"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        },
        {
            "set_tweak": "highlight"
        }
    ]
}
```

<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**

{{% added-in v="1.7" %}}

匹配拥有相应权限、`m.mentions` 属性中的 `room` 字段为 `true` 的发信人消息。

定义：

```json
{
    "rule_id": ".m.rule.is_room_mention",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_property_is",
            "key": "content.m\\.mentions.room",
            "value": true
        },
        {
            "kind": "sender_notification_permission",
            "key": "room"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "highlight"
        }
    ]
}
```

<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**

{{% changed-in v="1.7" %}}

自 v1.7 起，该规则已废弃，**仅在事件未含 [`m.mentions` 属性](#definition-mmentions) 时启用**。

匹配拥有权限且内容含有 `@room` 字符串（需全房通知）的消息。

定义：

```json
{
    "rule_id": ".m.rule.roomnotif",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "content.body",
            "pattern": "@room"
        },
        {
            "kind": "sender_notification_permission",
            "key": "room"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "highlight"
        }
    ]
}
```

**<a id="mruletombstone"></a>`.m.rule.tombstone`**

匹配所有类型为 `m.room.tombstone` 的状态事件。用于通知房间升级，效果类似于 `@room` 通知。

定义：

```json
{
    "rule_id": ".m.rule.tombstone",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.tombstone"
        },
        {
            "kind": "event_match",
            "key": "state_key",
            "pattern": ""
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "highlight"
        }
    ]
}
```

**<a id="mrulereaction"></a>`.m.rule.reaction`**

{{% added-in v="1.7" %}}

匹配所有类型为 `m.reaction` 的事件。用于抑制 [`m.reaction`](#mreaction) 事件的通知。

定义：

```json
{
    "rule_id": ".m.rule.reaction",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.reaction"
        }
    ],
    "actions": []
}
```

**`.m.rule.room.server_acl`**

{{% added-in v="1.4" %}}

抑制对 [`m.room.server_acl`](#mroomserver_acl) 事件的通知。

定义：

```json
{
    "rule_id": ".m.rule.room.server_acl",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.server_acl"
        },
        {
            "kind": "event_match",
            "key": "state_key",
            "pattern": ""
        }
    ],
    "actions": []
}
```

**`.m.rule.suppress_edits`**

{{% added-in v="1.9" %}}

抑制与[事件替换](#event-replacements)相关的通知。

定义：

```json
{
    "rule_id": ".m.rule.suppress_edits",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_property_is",
            "key": "content.m\\.relates_to.rel_type",
            "value": "m.replace"
        }
    ],
    "actions": []
}
```

##### 默认 Content 规则

<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**

{{% changed-in v="1.7" %}}

自 v1.7 起，该规则已废弃，**仅当事件无 [`m.mentions` 属性](#definition-mmentions) 时启用**。

匹配内容包含用户 Matrix ID 本地部分（以单词边界分隔）的消息。

定义（作为 `content` 规则）：

```json
{
    "rule_id": ".m.rule.contains_user_name",
    "default": true,
    "enabled": true,
    "pattern": "[the local part of the user's Matrix ID]",
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        },
        {
            "set_tweak": "highlight"
        }
    ]
}
```

##### 默认 Underride 规则

**`.m.rule.call`**

匹配所有传入 VOIP 呼叫事件。

定义：

```json
{
    "rule_id": ".m.rule.call",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.call.invite"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "ring"
        }
    ]
}
```

**`.m.rule.encrypted_room_one_to_one`**

匹配发送至仅有两名成员的加密房间内的任意加密事件。不同于普通推送规则，加密后事件无法基于内容匹配，故此规则表现为“全匹配”或“不匹配” —— 若为 1:1 房间内所有加密事件都匹配，否则全不匹配。

定义：

```json
{
    "rule_id": ".m.rule.encrypted_room_one_to_one",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "room_member_count",
            "is": "2"
        },
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.encrypted"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}
```

**`.m.rule.room_one_to_one`**

匹配仅有两名成员的房间内任意消息。

定义：

```json
{
    "rule_id": ".m.rule.room_one_to_one",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "room_member_count",
            "is": "2"
        },
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.message"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}
```

**`.m.rule.message`**

匹配所有聊天消息。

定义：

```json
{
     "rule_id": ".m.rule.message",
     "default": true,
     "enabled": true,
     "conditions": [
         {
             "kind": "event_match",
             "key": "type",
             "pattern": "m.room.message"
         }
     ],
     "actions": [
         "notify"
     ]
}
```

**`.m.rule.encrypted`**

匹配所有加密事件。由于加密，事件内容不能被常规匹配，本规则表现为组房内所有加密事件全匹配或全不匹配。

定义：

```json
{
     "rule_id": ".m.rule.encrypted",
     "default": true,
     "enabled": true,
     "conditions": [
         {
             "kind": "event_match",
             "key": "type",
             "pattern": "m.room.encrypted"
         }
     ],
     "actions": [
         "notify"
     ]
}
```

#### 推送规则：API

客户端可通过以下 API 全局或针对各设备获取、添加、修改、删除推送规则。

{{% http-api spec="client-server" api="pushrules" %}}

#### 推送规则：事件

当用户更改推送规则，会向所有客户端在下次 [`/sync`](#get_matrixclientv3sync) 请求的 `account_data` 部分发送 `m.push_rules` 事件。
事件内容为用户当前的全部推送规则。

{{% event event="m.push_rules" %}}

##### 示例

为 ID 为 `!dj234r78wl45Gh4D:matrix.org` 的房间创建禁止通知的规则：

    curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
    '{
       "actions" : []
     }'

禁止为用户名为 `@spambot:matrix.org` 的用户发送通知：

    curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
    '{
       "actions" : []
     }'

为所有消息内容含 “cake” 的消息始终通知，并设置专用提示音（规则 ID 为 `SSByZWFsbHkgbGlrZSBjYWtl`）：

    curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
    '{
       "pattern": "cake",
       "actions" : ["notify", {"set_tweak":"sound", "value":"cakealarm.wav"}]
     }'

添加规则：禁止通知以 “cake” 开头、“lie” 结尾的消息，并优先级高于上一条规则：

    curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
    '{
       "pattern": "cake*lie",
       "actions" : ["notify"]
     }'

为成员数不超过 10 的房间内含有 “beer” 的消息添加自定义通知音（优先级高于 room, sender, content 规则）：

    curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
    '{
       "conditions": [
         {"kind": "event_match", "key": "content.body", "pattern": "beer" },
         {"kind": "room_member_count", "is": "<=10"}
       ],
       "actions" : [
         "notify",
         {"set_tweak":"sound", "value":"beeroclock.wav"}
       ]
     }'

#### 客户端行为

客户端必须先配置 Pusher，才能接收推送通知。具体 API 如下所述。

{{% http-api spec="client-server" api="pusher" %}}

##### 列出通知

客户端可获取已收到通知的事件列表，帮助用户查看收到的重要消息摘要。

{{% http-api spec="client-server" api="notifications" %}}

##### 接收通知

服务器必须在客户端的 [`/sync`](#get_matrixclientv3sync) 流中包含未读通知数，并随计数变化更新。通知判定依赖于事件适用的推送规则。

对于加密事件，主服务器仅有限访问事件内容，推送规则需由客户端在*解密后*处理，客户端收到每条事件都需执行推送规则。这可能导致需修正从主服务器收到的未读通知数。

##### 标记通知为已读

当用户更新已读回执（无论使用 API 还是通过发送事件），在该事件之前（含自身）的通知必须被标记为已读。具体被影响的事件取决于是否使用了[线程已读回执](#threaded-read-receipts)。用户可同时发送 `m.read` 和 `m.read.private` 回执，两者都可清除通知。

如同一房间内用户同时拥有 `m.read` 和 `m.read.private`，应取更“新”或“更靠前”的回执为判断依据。例如，若事件 A、B、C、D 按时间升序排列，`m.read` 回执在事件 C，`m.read.private` 在事件 A，则用户已读至 C。如果 `m.read.private` 更新为 B 或 C，通知状态不变（`m.read` 回执仍领先）；如 `m.read.private` 更新为 D，则用户已读到 D（`m.read` 落后于 `m.read.private`）。

{{% added-in v="1.4" %}} 处理线程已读回执时，服务器需将通知数分配至各线程（主时间线看作一条线程）。判定事件属于哪个线程，服务器应按[event 关系](#forming-relationships-between-events)查找，直到遇到 `m.thread` 关系定义的根事件（详见[线程模块](#threading)），但不建议无限遍历。建议实现时至多跳 3 层，未找到线程即视为事件不属于线程。主要确保后续事件如 `m.reaction` 被正确划分为某线程。

#### 服务器行为

主服务器收到新事件时，为房间内每位本地用户（不含发信人）处理推送规则，结果可能为：

* 生成新的未读通知数；
* 向配置的推送网关发起请求。

新事件导致的未读通知数必须与事件本身一起在同一次 [`/sync`](#get_matrixclientv3sync) 响应中返回。

#### 推送网关行为

##### APNS 推荐

APNS 推送通知的具体格式灵活，由客户端应用与其推送网关约定。由于 APNS 需求发送者具有应用开发者的私钥，每个应用需有专属推送网关。推荐如下：

-   APNS Token 基于 base64 编码，直接用于 pushkey。
-   正式环境和沙箱环境使用不同的 app_id 。
-   APNS 推送网关不必等待 APNS 网关返回错误再响应；可记录失败，并在下次推送相同 pushkey 时返回 'rejected'。

#### 安全性注意事项

客户端需指定用于发送事件通知的推送网关 URL 。此 URL 必须为 HTTPS，*绝不能*是 HTTP。

推送通知会经过推送供应商，消息内容应尽量不随推送本体一起发送。推送网关应发送 "sync" 指令，指导客户端直接向主服务器获取新事件。