推送模板

大约 7 分钟

推送模板

功能说明

推送模板用于在默认离线推送内容不满足业务需求时，自定义推送通知的标题和内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。

你可以通过声网控制台open in new window 或 服务端 REST API 配置推送模板，并在发送消息时通过消息扩展字段指定模板名称和模板参数。

推送模板包括默认模板 default、detail 和自定义模板。默认模板适用于通用推送场景；自定义模板适用于需要按业务场景、语言或接收对象展示不同推送内容的场景。

推送模板具有以下特点：

  1. 推送模板的优先级高于 调用 API 设置通知栏的推送内容。
  2. 支持通过声网控制台open in new window 或 服务端 REST API 自定义服务端默认推送内容。
  3. 对于群组消息，你可以使用定向模板向某些用户推送与其他用户不同的离线通知。
  4. 接收方可配置推送模板：若发送方在发送消息时使用了推送模板，则推送通知栏中的显示内容以发送方的推送模板为准。
  5. 推送模板使用优先级：
    • 自定义模板的优先级高于默认模板。
    • 发送方在消息扩展字段中指定推送模板时，接收方即使设置了推送模板，收到推送通知后也按照发送方设置的推送模板显示。

开通功能

推送模板 是推送的高级功能。使用前，你需要在 声网控制台open in new window免费开通推送高级功能。激活后，如需关闭推送高级功能，必须联系商务，因为该操作会删除高级功能相关的所有配置。

设置推送模板

你可以通过以下两种方式设置离线推送模板：

推送模板相关的数据结构，详见 推送扩展字段。下面为在声网控制台设置离线推送模板。

离线推送模板开通后，推送模板 页面默认添加两个模板，default 和 detail。若未配置自定义推送模板，消息推送时自动使用默认模板，创建消息时无需传入模板名称。

  • default：默认情况下，推送标题为 您有一条新消息，推送内容为 请点击查看。若调用了 updatePushDisplayStyle 方法将 DisplayStyle 设置为 SimpleBanner，则默认推送模板为 default。
  • detail：默认情况下，推送标题为 您有一条新消息，推送内容为为消息发送方的推送昵称和消息内容。若调用了 updatePushDisplayStyle 方法将 DisplayStyle 设置为 MessageSummary，则默认推送模板为 detail。

默认推送模板支持修改推送标题和推送内容，但模板名称不能编辑。

点击添加模板，配置相关参数，添加自定义推送模板。

推送模板参数类型参数描述
模板名称String推送模板名称。
该参数必须填写。模板名称最多可包含 64 个字符，支持以下字符集：
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
标题/内容Array推送标题/内容。该参数必须填写。这两个参数的设置方式如下：
- 输入固定的推送标题/内容，例如，标题为 “您好”，内容为“您有一条新消息”。
- 内置参数填充：1. {$dynamicFrom}：按优先级从高到底的顺序填充好友备注、群昵称（仅限群消息）和推送昵称。2. {$fromNickname}：推送昵称。3. {$msg}：消息内容。
- 自定义参数填充：模板输入数组索引占位符，格式为: {0} {1} {2} ... {n}
对于默认模板 default，参数的前两种设置方式在创建消息时无需传入该参数，第三种设置方式则需要通过扩展字段传入。使用自定义模板时，这两个参数无论通过哪种方式设置，创建消息时均需通过扩展字段传入。

提示

自定义推送模板的级别比默认模板高。

img

推送模板参数在消息扩展 ext.em_push_template 中。推送模板参数的 JSON 结构如下：

{
    "ext":{
        "em_push_template":{
            "title_args":[
                "声网"
            ],
            "content_args":[
                "欢迎使用im-push",
                "加油"
            ]
        }
    }
}

# title: {0} = "声网"
# content: {0} = "欢迎使用im-push" {1} = "加油"

群昵称即群成员在群组中的昵称。若要在推送通知中展示群昵称，群成员在发送群消息时可通过扩展字段设置，JSON 结构如下：

  {
    "ext":{
            "em_push_ext":{
                "group_user_nickname":"Jane"
            }
        }
  }

发消息时使用推送模板

你可以在发送消息时选择推送模板，可通过三种方式设置推送模板。

提示

  1. 若使用默认模板 default 或 detail，消息推送时自动使用默认模板，创建消息时无需传入模板名称。
  2. 使用自定义模板时，推送标题 和 推送内容 参数无论通过哪种方式设置，创建消息时均需通过扩展字段传入。

使用固定内容的推送模板

使用固定内容的推送模板，通过 ext 扩展字段指定推送模板名称。

这种情况下，创建消息时无需传入 titleArgs 和 contentArgs 参数。

// 下面以文本消息为例，其他类型的消息设置方法相同。
EMMessage message = EMMessage.createSendMessage(EMMessage.Type.TXT);
EMTextMessageBody txtBody = new EMTextMessageBody("消息内容");
message.setTo("6006");
// 设置推送模板。
JSONObject pushObject = new JSONObject();
try {
    // 设置推送模板名称。设置前需在声网控制台或调用 REST 接口创建推送模板。
   //若为默认模板 `default` 或 `detail`，无需传入模板名称。
   //若为自定义模板，需传入模板名称。
    pushObject.put("name", "test7");

} catch (JSONException e) {
    e.printStackTrace();
}
// 将推送扩展设置到消息中。
message.setAttribute("em_push_template", pushObject);
// 设置消息状态回调。
message.setMessageStatusCallback(new EMCallBack() {...});
// 发送消息。
EMClient.getInstance().chatManager().sendMessage(message);

使用包含内置参数的推送模板

使用自定义或默认推送模板，模板中的推送标题和推送内容使用以下内置参数：

  • {$dynamicFrom}：服务器按优先级从高到底的顺序填充备注、群昵称（仅限群消息）和推送昵称。
  • {$fromNickname}：推送昵称。
  • {$msg}：消息内容。

群昵称即群成员在群组中的昵称，群成员在发送群消息时通过扩展字段设置，JSON 结构如下：

  {
    "ext":{
            "em_push_ext":{
                "group_user_nickname":"Jane"
            }
        }
  }

内置参数的介绍，详见 设置推送模板。

这种方式的示例代码与 使用固定内容的推送模板的相同。

使用包含自定义参数的推送模板

使用自定义推送模板，而且推送标题和推送内容为自定义参数：

例如，推送模板的设置如下图所示：

img

使用下面的示例代码后，通知栏中弹出的推送通知为：

img

// 下面以文本消息为例，其他类型的消息设置方法相同。
EMMessage message = EMMessage.createSendMessage(EMMessage.Type.TXT);
EMTextMessageBody txtBody = new EMTextMessageBody("消息内容");
message.setTo("6006");
// 设置推送模板。设置前需在声网控制台或调用 REST 接口创建推送模板。
JSONObject pushObject = new JSONObject();
JSONArray titleArgs = new JSONArray();
JSONArray contentArgs = new JSONArray();
try {
    // 设置推送模板名称。若不指定，设置默认推送模板的信息。
    pushObject.put("name", "push");
    // 设置填写模板标题的 value 数组。
    titleArgs.put("您");
    titleArgs.put("消息,");
    //...
    pushObject.put("title_args", titleArgs);
    // 设置填写模板内容的 value 数组。
    contentArgs.put("请");
    contentArgs.put("查看");
    //...
    pushObject.put("content_args", contentArgs);
} catch (JSONException e) {
    e.printStackTrace();
}
// 将推送扩展设置到消息中。
message.setAttribute("em_push_template", pushObject);
// 设置消息状态回调。
message.setMessageStatusCallback(new EMCallBack() {...});
// 发送消息。
EMClient.getInstance().chatManager().sendMessage(message);

消息接收方使用推送模板

消息接收方可以调用 setPushTemplate 方法传入推送模板名称，选择要使用的模板。

提示

若发送方在发送消息时使用了推送模板，则推送通知栏中的显示内容以发送方的推送模板为准。

EMClient.getInstance().pushManager().setPushTemplate("Template Name", new EMCallBack() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(int code, String error) {

    }
});
上次编辑于:
声网 IM 文档
© 声网 2026