配置消息的推送属性

开发者中心

IM 即时通讯

集成开发

配置消息的推送属性

更新时间： 2024/03/14 17:08:38

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

功能介绍

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

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

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

设置消息需要推送

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

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

NIMMessage *message = [[NIMMessage alloc] init];
message.text = @"消息示例";
NIMMessageSetting *setting = [[NIMMessageSetting alloc] init];
setting.apnsEnabled = NO; //设置为 无需推送
message.setting = setting;

群消息强制推送

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

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

参数	类型	说明
forcePush	BOOL	是否强制推送，默认为 YES，表示即使推送列表中的用户屏蔽了当前会话（如静音），仍能够推送当前推送内容给相应用户
userIds	NSArray< NSString * > *	需要强制推送的用户列表，如果设置为 nil，则推送给当前会话内的所有用户
apnsContent	NSString *	强制推送文案，最大长度 500 字符，推送给指定用户的特定推送文案，如果设置为 nil，则使用消息本身的推送文案（`NIMMessage#apnsContent`）

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

示例代码如下：

NIMMessageApnsMemberOption * messageApnsMemberoption = [[NIMMessageApnsMemberOption alloc] init];
messageApnsMemberoption.forcePush = YES;
messageApnsMemberoption.userIds = @[@"userId_1", @"userId_2"];
messageApnsMemberoption.apnsContent = @"Your APNs content here.";

textMessage.apnsMemberOption = messageApnsMemberoption;

设置推送文案

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

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

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

设置消息体的推送文案

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

发送设置完成的消息后，接收方的手机将会收到一条 APNs 推送，内容形式为"昵称:"+"推送文案"，其中，昵称为推送文案前缀。

示例代码如下：

NIMAudioObject *audioObject = [[NIMAudioObject alloc] initWithSourcePath:filePath];
NIMMessage *message = [[NIMMessage alloc] init];
message.messageObject = audioObject;
message.apnsContent = @"发来了一段语音";    //对方收到的推送文案

设置消息的推送文案前缀

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

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

示例代码如下：

NIMMessage *message = [[NIMMessage alloc] init];
message.text = @"消息示例";
message.apnsContent = @"推送消息示例";    //对方收到的推送文案 
NIMMessageSetting *setting = [[NIMMessageSetting alloc] init];
setting.apnsWithPrefix = NO;           //不需要前缀
message.setting = setting;

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

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

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

登录网易云信控制台，在控制台首页应用管理中选择应用进入应用配置页面。
单击 IM 即时通讯专业版下的功能配置按钮进入 IM 功能配置页。
顶部选择基础功能页签，开启自定义推送。
开启后，单击子功能配置，然后单击新增，添加自定义推送文案。

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

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

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
    // 上传devicetoken时携带自定义推送文案类型
    [[NIMSDK sharedSDK] updateApnsToken:deviceToken
                    customContentKey:@"customkey"];
}

将推送文案的显示类型设置为不显示详情。

// 获取当前设置
NIMPushNotificationSetting *setting = [NIMSDK sharedSDK].apnsManager.currentSetting;
// 设置为不显示推送详情
setting.type = NIMPushNotificationDisplayTypeNoDetail;
[[[NIMSDK sharedSDK] apnsManager] updateApnsSetting:setting completion:^(NSError *error) {}];

推送角标未读数

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

设置消息计入角标未读数

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

NIMMessage *message = [[NIMMessage alloc] init];
message.text = @"没有未读数的消息示例";
NIMMessageSetting *setting = [[NIMMessageSetting alloc] init];
setting.shouldBeCounted = NO;    //推送时不需要计入角标未读数
message.setting = setting;

设置角标未读数数值

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

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

手动赋值本地角标未读数

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

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

示例代码如下：
```
- (void)applicationDidEnterBackground:(UIApplication *)application {
    NSInteger count = [[[NIMSDK sharedSDK] conversationManager] allUnreadCount];
    [[UIApplication sharedApplication] setApplicationIconBadgeNumber:count];
}
```
自定义云信角标未读数

如果应用本身除了云信未读之外还有其他未读时，应用上的角标未读数数值应为云信未读数+其他未读数之和，但是由于云信服务器默认维护的未读数只有消息的未读数，这样会导致用用的角标未读数未计入应用的其他未读数。

在上述场景下，需要客户端提交应用的其他未读数至云信服务器，云信服务器才能管理应用的总未读数。

在初始化 SDK 之后，通过调用 registerBadgeCountHandler:注册获取 badge 数值的回调函数。并在回调中返回一个全局变量，后续在执行程序期间，按需修改此全局变量即可。SDK 会自动读取其中的返回值并传递给云信服务器。

示例代码如下：
```
[apnsManager registerBadgeCountHandler: ^NSUInteger{
    // Your code here.
    // 
}];
```

设置角标未读数上限：

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

登录网易云信控制台，在控制台首页应用管理中选择应用进入应用配置页面。
单击 IM 即时通讯专业版下的功能配置按钮进入 IM 功能配置页。
顶部选择基础功能页签，编辑iOS 应用角标未读数上限。

设置推送标题

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

方式一：通过设置消息体 NIMMessage - apnsPayload - apsField - alert中的 title 和 body 字段可以指定推送标题与推送文案，优先级最高。如配置了apsField 的 alert 字段，但是 title 为空或没有配置，那么将没有推送标题；body为空或没有配置，那么将没有推送文案；两者都为空或都没有配置，则推送标题和推送文案都没有。
方式二：如果未在云信消息体 NIMMessage - apnsPayload - 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 - apnsPayload来实现。设置 apnsPayload ，插入一对键为 sound 的键值对，即可实现推送铃声的配置。

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

示例代码如下：

NIMMessage *message = [[NIMMessage alloc] init];
message.text = @"消息示例";
message.apnsContent = @"发来了一条信息";
message.apnsPayload = @{@"sound":@"message.wav"};

设置推送通知栏

实现点击通知栏跳转

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

具体实现方法为：

在消息体的 NIMMessage - apnsPayload 中插入表示会话标识的信息（如自身的账号、群 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 及以上版本支持推送消息覆盖，即后一条推送内容覆盖前面推送内容。

登录网易云信控制台，在控制台首页应用管理中选择应用进入应用配置页面。
单击 IM 即时通讯专业版下的功能配置按钮进入 IM 功能配置页。
顶部选择全局功能页签，编辑撤回消息覆盖策略。
- 覆盖：撤回消息的推送会覆盖被撤回消息的原始推送。接收方仅显示 "xxx撤回了一条消息"（当前 vivo 推送不支持覆盖）
- 不覆盖（默认）：撤回消息的推送不会覆盖被撤回消息的原始推送，接收方会收到被撤回消息和撤回通知两条推送

以撤回消息的场景为例：

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

接口	说明
sendMessage:toSession:error:	发送消息
sendMessage:toSession:completion:	异步发送消息
sendCustomNotification:toSession:completion:	发送自定义系统通知

参数	类型	说明
setting	`NIMMessageSetting`	消息配置项其中 apnsEnabled 表示消息是否需要推送；apnsWithPrefix 表示推送是否需要带前缀（一般为昵称）；shouldBeCounted 表示该消息推送时是否要计入角标未读数
apnsMemberOption	`NIMMessageApnsMemberOption`	指定成员推送选项，包括是否强制推送，指定需要特殊推送的用户通过该选项进行一些更复杂的推送设定，目前只能在群会话中使用
apnsContent	NSString*	推送文案，最大长度 500 字符，撤回消息时该字段无效
apnsPayload	NSDictionary*	消息的推送 payload，可以通过该字段自定义消息推送 payload，支持字段参考苹果技术文档，最大长度 2018 字符，撤回消息时该字段无效

功能介绍

设置消息需要推送

群消息强制推送

设置推送文案

设置消息体的推送文案

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

推送角标未读数

设置消息计入角标未读数

设置角标未读数数值

设置推送标题

设置推送铃声

设置推送通知栏

实现点击通知栏跳转

覆盖通知栏内容

相关参考

API 参考

消息体的推送属性列表