配置消息的推送属性

开发者中心

IM 即时通讯

集成开发

配置消息的推送属性

更新时间： 2024/05/27 14:37:31

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

功能介绍

发送方可在发送消息/自定义系统通知时配置消息体（NIMMessage）的推送属性，包括消息是否需要离线推送、离线推送时是否计入应用角标展示的未读数、推送文案和推送 payload 等。

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

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

设置消息需要推送

发送方可以通过消息体中的是否需要推送参数（NIMMessage - NIMCustomMessageConfig - enablePush ），来设置该消息是否需要离线推送。

enablePush 默认为 YES，即默认需要推送，如不需要，可修改为 NO。示例代码如下：

message.config = NIMCustomMessageConfig(enablePush: true);
    return NimCore.instance.messageService
        .sendMessage(message: message, resend: false);

群消息强制推送

云信支持对于群消息的强制推送设置，即群消息接收者即使屏蔽了当前会话（如设置免打扰），仍能接收到该条推送。

发送方在发送消息时，通过消息体的指定成员推送选项字段 NIMMessage - memberPushOption 来实现，具体参数说明如下：

参数	类型	说明
isForcePush	Boolean	是否强制推送（仅针对 `forcePushList` 中的账户），true 为强制推送（默认），false 为不强制推送
forcePushList	List	需要强推的成员列表如果填 null，表示强制推送给该会话的所有成员，不为 null 时，最多可传入 100 个用户账号
forcePushContent	String	强制推送的文案，最大长度 500 字符，如果设置为 nil，则使用消息本身的推送文案（`pushContent`）

对于 forcePushList 中的用户，推送文案使用 NIMMessage#forcePushContent.pushContent；对于不在 forcePushList 中的用户，推送文案使用 NIMMessage#pushContent。
forcePushList 中的账户的推送文案显示形式又分两种情况：
- 当 isForcePush 为 YES 时，推送文案中不会包含发送者前缀（nick），直接为 forcePushContent。
- 当 isForcePush 为 NO 时，推送文案中目前包含了发送者的前缀（nick），即为 fromNick：forcePushContent。

示例代码如下：

void sendForcePushMessage() async {
    NIMMessage message = (await MessageBuilder.createTextMessage(
        sessionId: 'testTeamId',
        sessionType: NIMSessionType.team,
        text: '指定推送消息',
    )).data!;
    final memberPushOption = NIMMemberPushOption(
      isForcePush: true,
      forcePushContent: message.content,
      forcePushList: ['account1', 'account2']
    );
    NimCore.instance.messageService.sendMessage(
        message: message..memberPushOption = memberPushOption
    );
}

设置推送文案

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

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

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

设置消息体的推送文案

发送方可以通过设置消息体中的 pushContent 参数来设置该消息的推送文案，如果不设置，则使用默认的推送文案。

发送设置完成的消息后，接收方的手机将会收到一条 APNs 推送，内容形式为"昵称:"+"推送文案"。其中，昵称为推送文案前缀（默认需要前缀），具体请参见下文的设置推送文案前缀。

示例代码如下：

message.pushContent = 'You have a new Message';
    return NimCore.instance.messageService
        .sendMessage(message: message, resend: false);

设置消息的推送文案前缀

通过设置消息体的（NIMMessage - NIMCustomMessageConfig - enablePushNick ）参数来设置该消息的推送文案是否需要前缀，云信服务器向 APNs 请求推送时，前缀为用户昵称。

enablePushNick 默认为 YES，即默认需要推送文案前缀，如不需要，可修改为 NO。

示例代码如下：

 message.config = NIMCustomMessageConfig(enablePush: true,enablePushNick: true);
    return NimCore.instance.messageService
        .sendMessage(message: message, resend: false);

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

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

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

在云信控制台开通自定义推送文案功能，并在控制台添加自定义推送文案（功能配置->自定义推送文案->添加推送文案）。

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

在上传 devicetoken 的同时，设置自定义的推送文案类型（对应控制台中的自定义类型）。

/// 更新iOS deviceToken
/// [token] 当前设备的 devicetoken 
/// [customContentKey] 自定义本端推送内容, 设置key可对应业务服务器自定义推送文案; 传空字符串清空配置, null 则不更改

Future<NIMResult<void>> updateAPNSToken(Uint8List token, String? customContentKey);

调用 enablePushShowDetail 方法将推送文案的显示类型设置为不显示详情。
```
NimCore.instance.settingsService.enablePushShowDetail(false);
```

推送角标未读数

云信支持应用的角标未读数设置和管理。默认情况下，每一条消息的推送会让应用的角标未读数加 1。例如，当应用处于后台时，收到 5 条推送消息，则应用的角标未读数增加 5。

设置消息计入角标未读数

消息发送方在发送消息时，可以通过消息体的配置项 NIMMessage - NIMCustomMessageConfig - enableUnreadCount 字段来设置该消息推送时是否要计入角标未读数。示例代码如下：

message.config = NIMCustomMessageConfig(enableUnreadCount: true);

设置角标未读数数值

APNs 推送所附带的未读数是通过设置推送 payload 中的 badge 参数。

在云信服务中，不支持直接设置 badge，服务器对每个用户维护一个当前未读数，当服务器收到一条未读消息后，会自动在未读数上累加后填入推送的 badge 字段推送给接收端。

手动赋值本地角标未读数：

如果用户需要维护本地的角标未读数，那么需要用户在应用每次退到后台时，统计本地所有未读，并设置 badge，以此保证应用在前后台未读数一致。

例如，App 在后台收到一条消息，此时 App 的角标会变成 1；App 回到前台，会话的总未读数为 1，此时又收到一条消息，会话的总未读数变成 2。当 App 再次切到后台时，用户应调用iOS 系统方法将角标赋值为 2。

设置角标未读数上限：

云信侧发起的推送可以在云信控制台设置 iOS 应用角标未读数的上限值，可设置的角标未读数范围为 1-99。

在控制台首页应用管理中选择应用，然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
在基础功能页签下的iOS 应用角标未读数上限 中进行配置。

设置推送标题

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

方式一：通过设置消息体 NIMMessage - pushPayload - apsField - alert中的 title 和 body 字段可以指定推送标题与推送文案，优先级最高。如配置了apsField 的 alert 字段，但是 title 为空或没有配置，那么将没有推送标题；body为空或没有配置，那么将没有推送文案；两者都为空或都没有配置，则推送标题和推送文案都没有。
方式二：如果未在云信消息体 NIMMessage - pushPayload - apsField 中配置，而是直接通过苹果的 payload 字段配置了 "pushTitle": "标题内容"，则以此显示。

如果上述两种方式都没有配置，则不会显示推送标题。

若您无法在苹果的推送参数 payload 中配置 aps 字段，可以使用云信提供推送配置 payload - apsField 字段，直接对应 APNs 的 payload - aps 字段。

该字段仅适用于 iOS 接收，Android 无法解析此字段。

以下示例为通过云信 NIM 配置的带有 apsField 字段的 payload ：

{
    // 上述示例代码出于展示目的进行了格式化，实际发送的时候不要进行格式化。
    "key1": "value1", //自定义键值对
    "apsField": {
        "mutable-content": 1,
        "sound": "abc.wav",
        "alert": {
            "title": "推送标题",
            "body": "推送内容"
        },
        "key2": "value2"
    }
}

设置推送铃声

云信支持设置消息推送的铃声。

通过消息体的推送自定义字段 NIMMessage - pushPayload来实现。设置 pushPayload ，插入一对键为 sound 的键值对，即可实现推送铃声的配置。

推送音频的具体格式，具体请参见苹果官方文档。

示例代码如下：

var message = NIMMessage(messageType: NIMMessageType.text, timestamp: 0, messageDirection: NIMMessageDirection.outgoing);
message.content = '消息示例';
message.pushContent = '发来了一条信息';
message.pushPayload = {'sound':'message.wav'};

设置推送通知栏

实现点击通知栏跳转

云信支持实现通知栏跳转功能。具体场景为：应用的用户收到 APNs 离线推送后，应用弹出通出栏，用户点击通知栏进入指定的聊天界面。

具体实现方法为：

发送方在构造消息对象时，在 NIMMessage - pushPayload 中插入表示会话标识的信息（如自身的账号、群 ID、会话类型等），便于接收端获取 APNs - payload 的解析。
当接收端收到 APNs 推送时，解析 APNs - payload 得到 sessionid 和 sessiontype，并跳转到对应的界面。

示例代码如下：

json{
    // 上述示例代码出于展示目的进行了格式化，实际发送的时候不要进行格式化。
    "sessionid": "zhangsan", //表明该条消息的发送者的账号或者消息所属的群组id
    "sessiontype": "p2p",   //表明条消息对应的会话是单聊还是群聊等等
    "apsField": {
        "mutable-content": 1,
        "sound": "abc.wav",
        "alert": {
            "title": "推送标题",
            "body": "推送内容"
        },
        "key2": "value2"
    }
}

覆盖通知栏内容

iOS 10 及以上版本支持推送消息覆盖，即后一条推送内容覆盖前面推送内容。典型的撤回消息场景如下：

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

可以通过以下方式实现：

在发送消息时，在 NIMMessage - pushPayload 中插入 key 为 apns-collapse-id 的键值对，value 的内容建议使用 uuid 等字符串，用以唯一标识该消息。
当要撤回这条消息时，在撤回接口传参 apnsContent 中设置覆盖文案，在 pushPayload 中插入与被撤回消息相同的 apns-collapse-id。

这里以 iOS SDK 为例，当其他端发起撤回消息时，也同理。
该功能需要提前在云信控制台开通。

开通覆盖撤回消息推送功能：

在控制台首页应用管理中选择应用，然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
在基础功能页签下的撤回消息覆盖策略 中进行配置。

功能介绍

设置消息需要推送

群消息强制推送

设置推送文案

设置消息体的推送文案

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

推送角标未读数

设置消息计入角标未读数

设置角标未读数数值

设置推送标题

设置推送铃声

设置推送通知栏

实现点击通知栏跳转

覆盖通知栏内容

相关参考

API 参考

消息体的推送属性列表

接口	说明
sendMessage	发送消息
sendCustomNotification	发送自定义系统通知

参数	类型	说明
pushContent	String	自定义推送文案，最大长度 200 字符，撤回消息时该字段无效
pushPayload	Map< String, Object >	第三方自定义的推送属性，可以通过该字段自定义消息推送 Payload，支持字段参考第三方推送技术文档，最大长度 2048 字符，撤回消息时该字段无效
memberPushOption	`NIMMemberPushOption`	指定成员推送选项，包括是否强制推送，指定需要特殊推送的用户通过该选项进行一些更复杂的推送设定，目前只能在群会话中使用
config	`NIMCustomMessageConfig`	消息配置项其中 enablePush 表示消息是否需要推送；enablePushNick 表示推送是否需要带前缀（一般为昵称）；enableUnreadCount 表示该消息推送时是否要计入角标未读数