IM 即时通讯
Android
开发指南

配置消息的推送属性

更新时间: 2023/06/29 10:58:26

云信 NIM SDK 支持配置消息的推送相关属性。

功能介绍

发送方可在发送消息/自定义系统通知时配置消息体(NIMMessage)的推送属性,包括消息是否需要离线推送、推送文案、推送标题等。

当收到离线推送后,接收方可以设置通知栏的跳转,即点击通知栏后,就进入指定的聊天界面。

具体的属性说明,参见文末的推送属性列表

设置消息需要推送

发送方可以通过消息体中的是否需要推送参数(NIMMessage - CustomMessageConfig - enablePush),来设置该消息是否需要离线推送。

enablePush 默认为 true,即默认需要推送,如不需要,可修改为 false,即该消息不会触发推送。

可以通过调用getConfig 获取消息的推送配置,也可以调用 setConfig 修改消息的推送配置。

示例代码如下:

CustomMessageConfig config = new CustomMessageConfig();
config.enablePush = false;
textMessage.setConfig(config)

设置推送文案

云信支持设置消息的推送文案。

消息推送文案使用优先级如下:

  • 如果消息接收方设置的推送文案显示属性为“显示详情”(showNoDetail = false),那么优先显示接收到的消息的推送文案(消息体中的 PushContent字段内容),若发送方在发送消息时未设置消息的推送文案,则显示云信消息的内置文案(根据消息类型不同,内置文案不同,如文本消息类型对应的文案为“发来了一条消息”)。
  • 如果消息接收方设置的推送文案显示属性为“不显示详情”(showNoDetail = true ),那么优先显示提前设置好的自定义的推送文案(自定义推送文案功能需要单独开通,并且自定义的推送文案需要提前在控制台中添加。具体操作请参见下文的使用不显示详情的自定义推送文案),若未设置,则使用默认的推送文案是:“你收到一条新消息”。

设置消息体的推送文案

发送方可以通过设置消息体中的 PushContent 参数来设置该消息的推送文案。

发送设置好推送文案的消息后,接收方登录后会收到一条推送消息,内容形式为"昵称:"+"推送文案"。其中,昵称为推送文案前缀(默认需要前缀),具体请参见下文的设置推送文案前缀

可以通过调用getPushContent 获取消息的推送文案,也可以调用 setPushContent 设置消息的推送文案。

示例代码如下:

// 获取消息的推送文案
String pushContent = textMessage.getPushContent();
// 设置消息的推送文案
textMessage.setPushContent("Set the push content you want.");

设置消息的推送文案前缀

通过消息体中的是否需要推送前缀参数(CustomMessageConfig.enablePushNick),来设置该消息是否需要推送文案前缀,云信服务器向第三方推送服务端请求推送时,前缀为用户昵称。

enablePushNick 默认为 true,即默认需要推送文案前缀,如不需要,可修改为 flase。

可以通过调用getConfig 获取消息的推送配置,也可以调用 setConfig 修改消息的推送配置。

示例代码如下:

CustomMessageConfig config = new CustomMessageConfig();
config.enablePushNick = false;
textMessage.setConfig(config)

使用不显示详情的自定义推送文案

如果消息接收方将推送文案属性设置为不显示详情showNoDetail = true),如果没有单独配置自定义的推送文案,那么将使用云信内置的默认推送文案:“你收到一条新消息”。

若根据您的业务需求,需要使用自定义的推送文案,可以通过以下步骤实现。

  1. 在云信控制台开通并添加自定义推送。

    在控制台首页应用管理选择应用,再进入产品功能 > IM 即时通讯 > 基础功能,找到并开启自定义推送开启自定义推送.png

    单击并进入子功能配置,单击新增添加自定义推送文案。 自定义推送文案.png

    最多可以配置 100 种自定义推送文案,每种自定义文案用一个自定义类型来标识。

  2. 在初始化时,通过配置 SDKOptions.customPushContentType 来设置自定义的推送文案类型(对应控制台中的自定义类型)。

    SDKOptions.customPushContentType = "custom_push_content_type"
    
  3. 将推送文案属性设置为不显示详情。示例代码如下:

    // boolean showNoDetail = true;
    NIMClient.getService(MixPushService.class).setPushShowNoDetail(showNoDetail).setCallback(
            new RequestCallbackWrapper<Void>() {
                @Override
                public void onResult(int code, Void result, Throwable exception) {
                    if (code == ResponseCode.RES_SUCCESS) {
                        // 设置成功
                    } else {
                        // 设置失败
                    }
                }
            });
    

设置推送标题

目前云信发起的推送支持以下两种方式来设置推送标题:

  • 发送方通过消息体的推送自定义字段 PushPayload 来配置推送标题。 通过 setPushPayload配置 "pushTitle":"标题内容",则以此显示,优先级最高。
  • 如果没有配置,则使用云信默认的推送标题:点对点消息(P2P)推送标题默认为用户昵称(如果没有设置用户昵称,则点对点消息推送标题默认为新消息),群消息推送标题默认为群名称

示例代码如下:

CustomNotification notification = new CustomNotification();
Map<String, Object> payloadMap = new HashMap<>();
notification.setPushPayload(payloadMap);

设置推送通知栏跳转方式

发送方在发送消息前,在云信消息体的 PushPayload 中传入通知栏消息点击行为配置。当接收方收到离线推送后,可以设置通知栏跳转动作,即点击通知栏后,就进入指定的聊天界面。

小米推送

您可以在Application#oncreate的主进程中进行 MixPushMessageHandleronNotificationClicked事件注册,监听小米推送通知栏点击之后的回调。

返回 true,表示开发者自行处理第三方推送通知栏点击事件,SDK 将不再处理;返回 false 表示仍然使用 SDK 提供默认的点击后的跳转。

发送方:

  1. 设置云信消息体中 PushPayload 的消息点击行为:
// set PushPayload
Map<String, Object> pushPayload = new HashMap<>();
pushPayload.put("sessionID", "123456");
textMessage.setPushPayload(pushPayload);

// get PushPayload
String sessionId = payload.get("sessionID");
if (sessionId != null ) {   
    // set your click action here.
}
  1. 注册 onNotificationClicked事件。
public class DemoMixPushMessageHandler implements MixPushMessageHandler {
    @Override
    public boolean onNotificationClicked(Context context, Map<String, String> payload) {
        String sessionId = payload.get("sessionID");
        if (sessionId != null ) {   
            Intent notifyIntent = new Intent();
            // set your intent param here
            context.startActivity(notifyIntent);
        }
    }
}

接收方:

当接收方收到小米推送时,处理方式请参考通知栏通知的点击行为

华为推送

发送方:

设置云信消息体中 PushPayload 的消息点击行为,即在 PushPayload 中传入 key 为 hwField 的 Map 或者 JsonObject 类型的数据,通过 click_action 字段实现自定义通知栏的跳转,同时还可传入发送者的账号(accid)/ 群组 ID 与类型(单聊或群聊)等信息,这些信息将被透传到推送的接收方。数据的参数填写方法请参考华为开放平台:HTTPS下行消息。示例代码如下:

Intent hwIntent = new Intent(Intent.ACTION_VIEW);
String intentStr = String.format(
        "pushscheme://com.huawei.codelabpush/deeplink?sessionID=%s&sessionType=%s",
        sessionId,  // 发送者的账号(accid)/ 群组 ID 
        sessionType // 类型(单聊或群聊)
);
hwIntent.setData(Uri.parse(intentStr));
hwIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
String intentUri = hwIntent.toUri(Intent.URI_INTENT_SCHEME);
//点击事件的内容
JSONObject clickAction = new JSONObject();
//通知的内容
JSONObject notification = new JSONObject();

try {
    clickAction.putOpt("type", 1)
            .putOpt("intent", intentUri);
    notification.putOpt("click_action", clickAction);
    pushPayload.put("hwField", notification);
} catch (JSONException e) {
    e.printStackTrace();
}

接收方:

当接收方收到华为推送时,处理方式请参考华为开放平台:点击通知消息

荣耀推送

发送方:

设置云信消息体中 PushPayload 的消息点击行为,即在 PushPayload 中传入 key 为 honorField 的 Map 或者 JsonObject 类型的数据,通过 clickAction 字段实现自定义通知栏的跳转,同时还可传入发送者的账号(accid)/ 群组 ID 与类型(单聊或群聊)等信息,这些信息将被透传到推送的接收方。数据的参数填写方法请参考。示例代码如下:

Intent honorIntent = new Intent(Intent.ACTION_VIEW);
String intentStr = String.format(
        "pushscheme://link?sessionID=%s&sessionType=%s",
        sessionId,  // 发送者的账号(accid)/ 群组 ID 
        sessionType // 类型(单聊或群聊)
);
honorIntent.setData(Uri.parse(intentStr));
honorIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
String intentUri = honorIntent.toUri(Intent.URI_INTENT_SCHEME);
//点击事件的内容
JSONObject clickAction = new JSONObject();
//通知的内容
JSONObject notification = new JSONObject();

try {
    clickAction.putOpt("type", 1)
            .putOpt("intent", intentUri);
    notification.putOpt("clickAction", clickAction);
    pushPayload.put("honorField", notification);
} catch (JSONException e) {
    e.printStackTrace();
}

接收方:

当接收方收到荣耀推送时,处理方式请参考荣耀-下行消息

OPPO 推送

发送方:

设置云信消息体中 PushPayload 的消息点击行为,即在 PushPayload 中传入 key 为 oppoField 的 Map 或者 JsonObject 类型的数据,通过 click_action_type 字段实现自定义通知栏的跳转,同时还可传入发送者的账号(accid)/ 群组 ID 与类型(单聊或群聊)等信息,这些信息将被透传到推送的接收方。数据的参数请参考OPPO 开放平台:通知栏消息。示例代码如下:

// oppoField
Map<String, Object> oppoField = new HashMap<>();
Editable oppoChannelId = oppoChannelIdET.getText();
oppoField.put("click_action_type", 1);
oppoField.put("click_action_activity", "com.oppo.codelabpush.intent.action.test");
// oppoField.put("click_action_type", 4);
// oppoField.put("click_action_activity", "com.netease.nim.demo.main.activity.MixPushActivity");
JSONObject obj = new JSONObject();
try {
    obj.putOpt("sessionID", sessionType == SessionTypeEnum.P2P ? TestCache.getAccount() : msg.getSessionId());
    obj.putOpt("sessionType", sessionType.getValue());
} catch (JSONException e) {
    e.printStackTrace();
}
oppoField.put("action_parameters", obj.toString());
pushPayload.put("oppoField", oppoField);

接收方:

当接收方收到 OPPO 推送时,处理方式请参考OPPO开放平台:通知栏消息

谷歌推送

点击谷歌推送通知栏之后,直接启动应用入口 Activity,通过 Intent 携带数据,SDK 提供接口判断是否是云信侧集成的 FCM Intent。

通过调用 MixPushService 提供的 isFCMIntentparseFCMPayload 接口处理 FCM payload。示例代码如下:

if (NIMClient.getService(MixPushService.class).isFCMIntent(intent)) {
    String payload = NIMClient.getService(MixPushService.class).parseFCMPayload(intent);
}

即时通讯 Demo 中,在 WelcomeActivity.java 的 onIntent 中判断:if (NIMClient.getService(MixPushService.class).isFCMIntent(intent)),具体代码请参考 Demo。

其他推送

对于推送,发送方在构造消息对象时,需要通过 setPushPayload 插入表示会话标识的信息(如自身的账号、群id、会话类型等),便于接收端获取到 Payload 时的解析。

示例代码如下:

Map<String, Object> pushPayload = new HashMap<>();
pushPayload.put("sessionID", "123456");
textMessage.setPushPayload(pushPayload);

覆盖通知栏内容

安卓支持推送消息覆盖(除 vivo),即后一条推送内容覆盖前面推送内容。可以前往 云信控制台-选择对应的应用-功能配置(IM 专业版)-消息撤回配置-撤回消息是否覆盖原始消息推送 进行设置。

控制台功能配置.png

消息撤回设置.png

以撤回消息的场景为例:

用户 A 发消息给用户 B,产生第三方推送,文案内容为“你好”。然后用户 A 撤回了此条消息,此时通知栏中的“你好”变为预设的“对方撤回了一条消息”。

消息体推送属性列表

参数 类型 说明
Config CustomMessageConfig 消息配置项
其中 enablePush 表示消息是否需要推送;enablePushNick 表示推送是否需要带前缀(一般为昵称)
Content String 当消息类型不是文本(MsgTypeEnum#text)时,该字段表示消息推送的显示文本,最大长度为 500 字符
SDK 1.7.0及以上版本建议使用pushContent
PushContent String 自定义推送文案,最大长度 500 字符,撤回消息时该字段无效
SDK 1.7.0及以上版本建议使用此字段,不要使用 setContent 来设置推送文案
PushPayload Map< String, Object > 第三方自定义的推送属性,可以通过该字段自定义消息推送 Payload,支持字段参考第三方推送技术文档,最大长度 2048 字符,撤回消息时该字段无效
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 设置消息需要推送
  • 设置推送文案
  • 设置消息体的推送文案
  • 使用不显示详情的自定义推送文案
  • 设置推送标题
  • 设置推送通知栏跳转方式
  • 小米推送
  • 华为推送
  • 荣耀推送
  • OPPO 推送
  • 谷歌推送
  • 其他推送
  • 覆盖通知栏内容
  • 消息体推送属性列表