离线推送的消息扩展说明

大约 6 分钟

离线推送的消息扩展说明

环信即时通讯 IM 支持 APNs 推送和 Android 厂商离线推送，包括华为、荣耀、FCM、小米、魅族、OPPO 和 vivo。使用离线推送时，你可以通过消息扩展字段实现推送相应功能，例如，设置推送模板中的推送标题和内容、设置仅接收提及（@）某些用户的推送通知等。

推送扩展字段

payload.ext 结构如下：

字段类型描述
em_push_filterObject推送过滤。
em_at_listList<String>@列表。
em_push_template Object推送模板。
em_ignore_notificationBoolean静默消息开关，true 表示不推送。
em_force_notificationBoolean强制推送开关，true 则不检查用户是否开启免打扰。
em_apns_extObjectAPNs 配置。
em_android_push_extObjectAndroid 配置。
em_harmony_push_extObject鸿蒙推送扩展配置。
em_push_extObject通用的配置。

em_push_filter 结构如下：

字段类型描述
accept_device_idList<String>接收推送通知的设备 ID 列表。
ignore_device_idList<String>不接收推送通知的设备 ID 列表。
accept_notifier_nameList<String>接收推送的证书名列表。
ignore_notifier_nameList<String>不接收推送的证书名列表。

em_push_template 结构如下：

字段类型描述
nameString推送模板名称。
title_argsList<String>推送模板标题参数，内置参数：发送方昵称 {$fromNickname}。
content_argsList<String>推送模板内容参数，内置参数：消息内容 {$msg}，如果开通了翻译，消息内容会跟随翻译结果显示。
directed_templateObject定向推送模板。此类模板适用于群组消息的离线推送，其中的字段如下表所示。

定向模板中的字段：

字段类型作用
targetArray<String>用户 ID 列表，传入的用户 ID 必须为全部小写，否则不生效。
nameString推送模板名称。
title_argsArray<String>推送模板标题。
content_argsArray<String>推送模板内容。

关于如何使用定向模板，详见使用示例。

关于 title_args 和 content_args 字段的设置，详见推送模板文档。

em_push_ext 结构如下：

字段类型描述
titleString自定义推送标题。
contentString自定义推送内容。
customObject自定义推送扩展参数(t, f, m, g, e) 中 e 的内容。
group_user_nicknameString发送方群组昵称（用于推送显示替换发送方信息）。

em_apns_ext 结构如下：

字段类型描述
em_push_categoryStringAPNs 推送配置，推送通知类别。
em_push_mutable_contentBooleanAPNs 推送配置，true 为富文本推送通知，false 则为普通通知。
em_push_soundStringAPNs 推送配置，自定义铃声，Library/Sounds/ 目录下的 aiff、wav 或 caf 文件，例如 appsound.caf。
em_push_badgeIntegerAPNs 推送配置，自定义角标数。

em_android_push_ext 结构如下：

字段类型描述
fcm_optionsObjectFCM SDK 功能选项。
fcm_channel_idStringFCM 推送通道（最高优先级）。
honor_click_actionString荣耀点击跳转，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 荣耀 页面设置的 Action 参数的配置。
honor_importanceString荣耀推送优先级：
- LOW：低优先级；
- （默认）NORMAL：普通优先级。
honor_target_user_typeInteger推送用户类型：
- 0：普通
- 1：测试
huawei_target_user_typeInteger推送用户类型：
- 0：普通
- 1：测试
huawei_categoryString完成自分类权益申请open in new window后，用于标识消息类型，确定消息提醒方式open in new window，对特定类型消息加快发送，取值如下：华为官方文档中category字段的解释open in new window。该参数的设置优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 华为 页面设置的 Category 参数的配置。
huawei_receipt_idString华为回执地址 ID。
huawei_click_actionString华为点击跳转 action，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 华为 页面设置的 Action 参数的配置。
huawei_channel_idString华为推送通道（最高优先级）。
meizu_click_activityString魅族点击跳转 activity，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 魅族 页面设置的 Activity 参数的配置。
oppo_channel_idStringOPPO 推送通道（最高优先级），优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > OPPO 页面设置的 Activity 参数的配置。
oppo_click_activityStringOPPO 点击跳转 activity，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > OPPO 页面设置的 Activity 参数的配置。
vivo_categoryStringvivo 二级分类配置，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > VIVO 页面设置的 Category 参数的配置。
vivo_click_activityStringvivo 点击跳转 activity，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > VIVO 页面设置的 Activity 参数的配置。
xiaomi_channel_idString小米通道 ID，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 小米 页面设置的 Channel ID 参数的配置。
xiaomi_click_actionString小米点击跳转 action，优先级高于在环信即时通讯控制台的即时通讯 > 功能配置 > 消息推送 > 证书管理 > 添加推送证书 > 小米 页面设置的 Action 参数的配置。

em_harmony_push_ext 结构如下：

字段类型描述
categoryString消息分类。
click_actionString点击跳转应用内页。
is_test_messageBoolean是否是推送测试消息(beta 版仅支持测试)。
notify_idInteger通知 ID，相同的 ID 通知替换。
receipt_idString回执 ID。

示例

离线推送相关的扩展字段

离线推送的消息扩展字段如下所示：

{
    "ext": {
        "em_push_filter": {
            "accept_device_id": [

            ],
            "ignore_device_id": [

            ],
            "accept_notifier_name": [

            ],
            "ignore_notifier_name": [

            ]
        },
        "em_at_list": [
            "abc"
        ],
        "em_push_template": {
            "name": "test6",
            "title_args": [
                "test1"
            ],
            "content_args": [
                "{$fromNickname}",
                "{$msg}"
            ]
        },
        "em_push_ext": {
            "custom": {
                "test": 1
            },
            "group_user_nickname": "happy"
        },
        "em_ignore_notification": false,
        "em_force_notification": true,
        "em_apns_ext": {
            "em_push_title": "您有一条新消息",
            "em_push_content": "您有一条新消息",
            "em_push_category": "",
            "em_push_mutable_content": true,
            "em_push_sound": "appsound.mp3",
            "em_push_badge": 1
        },
        "em_android_push_ext": {
            "fcm_options": {
                "key": "value"
            },
            "fcm_channel_id": "",
            "honor_click_action": "",
            "honor_importance": "",
            "honor_target_user_type": 0,
            "huawei_target_user_type": 0,
            "huawei_category": "",
            "huawei_receipt_id": "",
            "huawei_click_action": "",
            "huawei_channel_id": "",
            "meizu_click_activity": "",
            "xiaomi_channel_id": "",
            "oppo_channel_id": "",
            "oppo_click_activity": "",
            "vivo_category": "",
            "vivo_click_activity": "",
            "xiaomi_channel_id": "",
            "xiaomi_click_action": "",
        },
        "em_harmony_push_ext": {
          "click_action": "com.a.b.shot",
          "category": "IM",
          "notify_id": 1,
          "receipt_id": "RCP78C959D4",
          "is_test_message":true
       }
    }
}

使用定向模板

下面介绍如何使用定向模板实现群组 @ 消息的自定义推送通知：

  1. 创建针对群 @ 用户的推送模板。
{
    "name": "at_push_template",
    "title_pattern": "{0}",
    "content_pattern": "{0}:{1}"
}
  1. 在群组中发送 @ 消息时使用定向推送模板。例如，在群组中 @ hxtest。
{
    "em_push_template": {
        "name": "at_push_template",
        "title_args": [
            "群组名"
        ],
        "content_args": [
            "张三",
            "发来一条消息"
        ],
        "directed_template": {
            "target": [
                "hxtest"
            ],
            "name": "at_push_template",
            "title_args": [
                "群组名"
            ],
            "content_args": [
                "张三",
                "在群里@了你"
            ]
        }
    }
}

另外，对于被提及的用户之外的其他用户，推送内容也并非一定要用模板，也可用推送扩展字段自定义标题和内容：

{
    "em_push_template": {
        "directed_template": {
            "target": [
                "hxtest"
            ],
            "name": "at_push_template",
            "title_args": [
                "群组名"
            ],
            "content_args": [
                "张三",
                "在群里@了你"
            ]
        }
    },
    "em_push_ext": {
        "title": "群组名",
        "content": "张三:发来一条消息"
    }
}
  1. 推送通知内容显示。

群组被 @ 的用户收到的通知如下图所示：

img

群组中其他用户收到的通知如下图所示：

img

环信 IM 文档 Version: 1.0.0 ©️环信