Merge pull request #1050 from haoxiuwen/doc-v2

Modify Offline Push Docs

docs/document/android/push/push_display.md

@@ -59,7 +59,9 @@ EMPushManager.DisplayStyle style = pushConfigs.getDisplayStyle();
 
 ## 使用推送模板
 
-推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。推送模板包括默认推送模板 `default` 和自定义推送模板，你可以通过以下两种方式设置：
+推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。推送模板包括默认推送模板 `default` 和自定义推送模板。对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
+你可以通过以下两种方式设置：
 
 - [调用 REST API 配置](/document/server-side/push.html#使用推送模板)。
 - 在[环信即时通讯云控制台](https://console.easemob.com/user/login)设置推送模板，详见[控制台文档](/product/enable_and_configure_IM.html#配置推送模板)。
@@ -77,7 +79,9 @@ EMPushManager.DisplayStyle style = pushConfigs.getDisplayStyle();
    - 若发送方发消息时设置了推送模板，接收方即使设置了推送模板，收到推送通知后也按照发送方设置的推送模板显示。
 
 :::tip
-设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+1. 设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+
+2. 推送模板相关的数据结构，详见[推送扩展字段](/server-side/push_extension.html)。
 :::
 
 ### 发消息时使用推送模板

docs/document/harmonyos/push/push_display.md

@@ -38,7 +38,9 @@ ChatClient.getInstance().pushManager()?.updatePushDisplayStyle(displayStyle).the
 
 ## 使用推送模板
 
-你可以使用推送模板设置推送标题和内容。推送模板包括默认推送模板 `default` 和自定义推送模板，你可以通过以下两种方式设置：
+推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。推送模板包括默认推送模板 `default` 和自定义推送模板。对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
+你可以通过以下两种方式设置：
 
 - [调用 REST API 配置](/document/server-side/push.html#使用推送模板)。
 - 在[环信即时通讯云控制台](https://console.easemob.com/user/login)设置推送模板，详见[控制台文档](/product/enable_and_configure_IM.html#配置推送模板)。
@@ -60,6 +62,12 @@ ChatClient.getInstance().pushManager()?.updatePushDisplayStyle(displayStyle).the
 3. 接收方设置了推送模板。
 4. 发送消息时通过消息扩展字段指定模板名称。
 
+:::tip
+1. 设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+
+2. 推送模板相关的数据结构，详见[推送扩展字段](/server-side/push_extension.html)。
+:::
+
 #### **发送消息时使用推送模板**
 
 创建模板后，你可以在发送消息时选择此推送模板，分为以下三种情况：

docs/document/ios/push/push_display.md

@@ -80,6 +80,8 @@
 - [调用 REST API 配置](/document/server-side/push.html#使用推送模板)。
 - 在[环信即时通讯云控制台](https://console.easemob.com/user/login)设置推送模板，详见[控制台文档](/product/enable_and_configure_IM.html#配置推送模板)。
 
+对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
 使用推送模板有以下优势：
 
 1. 自定义修改环信服务端默认推送内容。   
@@ -93,7 +95,9 @@
    - 若发送方发消息时设置了推送模板，接收方即使设置了推送模板，收到推送通知后也按照发送方设置的推送模板显示。
 
 :::tip
-设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+1. 设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+
+2. 推送模板相关的数据结构，详见[推送扩展字段](/server-side/push_extension.html)。
 :::
 
 ### 发送消息时使用推送模板

docs/document/react-native/push/push_display.md

@@ -65,11 +65,15 @@ ChatClient.getInstance()
 
 ## 使用推送模板
 
-推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。推送模板包括默认推送模板 `default` 和自定义推送模板，你可以通过以下两种方式设置：
+推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。推送模板包括默认推送模板 `default` 和自定义推送模板。对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
+你可以通过以下两种方式设置：
 
 - [调用 REST API 配置](/document/server-side/push.html#使用推送模板)。
 - 在[环信即时通讯云控制台](https://console.easemob.com/user/login)设置推送模板，详见[控制台文档](/product/enable_and_configure_IM.html#配置推送模板)。
 
+对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
 使用推送模板有以下优势：
 
 1. 自定义修改环信服务端默认推送内容。
@@ -83,7 +87,9 @@ ChatClient.getInstance()
    - 若发送方发消息时设置了推送模板，接收方即使设置了推送模板，收到推送通知后也按照发送方设置的推送模板显示。
 
 :::tip
-设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+1. 设置推送模板为推送的高级功能，使用前需要在[环信即时通讯控制台](https://console.easemob.com/user/login)的**即时通讯 > 功能配置 > 功能配置总览**页面激活推送高级功能。如需关闭推送高级功能必须联系商务，因为该操作会删除所有相关配置。
+
+2. 推送模板相关的数据结构，详见[推送扩展字段](/server-side/push_extension.html)。
 :::
 
 ### 发消息时使用推送模板

docs/document/server-side/push.md

@@ -814,6 +814,8 @@ curl -L -X GET 'https://XXXX/XXXX/XXXX/users/XXXX/notification/language' \
 
 你可以使用推送模板设置推送标题和内容。你可以调用以下 REST API 配置默认推送模板 `default` 和自定义推送模板。除此之外，你也可以在[环信即时通讯云控制台](https://console.easemob.com/user/login)设置推送模板，详见[控制台文档](enable_and_configure_IM.html#配置推送模板)。
 
+对于群组消息，你可以使用定向模板将离线通知只发送给特定用户，或向某些用户推送与其他用户不同的离线通知。
+
 使用推送模板有以下优势：
 
 1. 自定义修改环信服务端默认推送内容。   

docs/document/server-side/push_extension.md

@@ -1,4 +1,4 @@
- # 离线推送的消息扩展说明
+# 离线推送的消息扩展说明
 
 环信即时通讯 IM 支持 APNs 推送和 Android 厂商离线推送，包括华为、荣耀、FCM、小米、魅族、OPPO 和 vivo。使用离线推送时，你可以通过消息扩展字段实现推送相应功能，例如，设置推送模板中的推送标题和内容、设置仅接收提及（`@`）某些用户的推送通知等。
 
@@ -34,6 +34,18 @@
 | `name`         | String       | 推送模板名称。                                                 |
 | `title_args`   | `List<String>` | 推送模板标题参数，内置参数：发送方昵称 `{$fromNickname}`。      |
 | `content_args` | `List<String>` | 推送模板内容参数，内置参数：消息内容 `{$msg}`，如果开通了翻译，消息内容会跟随翻译结果显示。 |
+| `directed_template` | Object        | 定向推送模板。此类模板适用于群组消息的离线推送，其中的字段如下表所示。    |
+
+定向模板中的字段：
+
+| 字段           | 类型          | 作用             |
+| -------------- | ------------- | ---------------- |
+| `target`       | Array<String> | 用户 ID 列表，传入的用户 ID 必须为全部小写，否则不生效。     |
+| `name`         | String        | 推送模板名称。     |
+| `title_args`   | Array<String> | 推送模板标题。 |
+| `content_args` | Array<String> | 推送模板内容。 |
+
+关于如何使用定向模板，详见[使用示例](#使用定向模板)。
 
 关于 `title_args` 和 `content_args` 字段的设置，详见[推送模板文档](push.html#使用推送模板)。
 
@@ -89,6 +101,8 @@
 
 ## 示例
 
+### 离线推送相关的扩展字段
+
 离线推送的消息扩展字段如下所示：
 
 ```json
@@ -170,8 +184,85 @@
 }
 ```
 
+### 使用定向模板
+
+下面介绍如何使用定向模板实现群组 @ 消息的自定义推送通知：
+
+1. 创建针对群 @ 用户的推送模板。
+
+```json
+{
+    "name": "at_push_template",
+    "title_pattern": "{0}",
+    "content_pattern": "{0}:{1}"
+}
+```
+
+2. 在群组中发送 @ 消息时使用定向推送模板。例如，在群组中 @ `hxtest`。
+
+```json
+{
+    "em_push_template": {
+        "name": "at_push_template",
+        "title_args": [
+            "群组名"
+        ],
+        "content_args": [
+            "张三",
+            "发来一条消息"
+        ],
+        "directed_template": {
+            "target": [
+                "hxtest"
+            ],
+            "name": "at_push_template",
+            "title_args": [
+                "群组名"
+            ],
+            "content_args": [
+                "张三",
+                "在群里@了你"
+            ]
+        }
+    }
+}
+```
+
+另外，对于被提及的用户之外的其他用户，推送内容也并非一定要用模板，也可用推送扩展字段自定义标题和内容：
+
+```json
+{
+    "em_push_template": {
+        "directed_template": {
+            "target": [
+                "hxtest"
+            ],
+            "name": "at_push_template",
+            "title_args": [
+                "群组名"
+            ],
+            "content_args": [
+                "张三",
+                "在群里@了你"
+            ]
+        }
+    },
+    "em_push_ext": {
+        "title": "群组名",
+        "content": "张三:发来一条消息"
+    }
+}
+```
+
+3. 推送通知内容显示。
+
+群组被 @ 的用户收到的通知如下图所示：
+
+![img](/images/server-side/[email protected])
 
+群组中其他用户收到的通知如下图所示：
 
+![img](/images/server-side/push_other.png)