云信 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	是否强制推送（仅针对 userIds 中的账户），默认为 NO，不强制推送。若设置为 YES，表示即使设置了该群的群消息免打扰或全局的免打扰，仍能够推送当前推送内容给相应用户
userIds	NSArray< NSString * > *	需要强制推送的用户列表，如果设置为 nil，则推送给当前会话内的所有用户；不为 nil 时，最多可传入 100 个用户账号
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），如果没有单独配置自定义的推送文案，那么将使用云信内置的默认推送文案：“你收到一条新消息”。

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

1. 在控制台首页 应用管理 中选择应用，然后单击 IM 即时通讯 下的 功能配置 按钮进入功能配置页。

   

2. 顶部选择 基础功能 页签，开启 自定义推送。

   

3. 开启后，单击 子功能配置，然后单击 新增，添加自定义推送文案。

   

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

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

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

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

   // 获取当前设置
   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。

1. 在控制台首页 应用管理 中选择应用，然后单击 IM 即时通讯 下的 功能配置 按钮进入功能配置页。

   

2. 顶部选择 基础功能 页签，编辑 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 离线推送后，应用弹出通出栏，用户点击通知栏进入指定的聊天界面。

具体实现方法为：

1. 在消息体的 NIMMessage - apnsPayload 中插入表示会话标识的信息（如自身的账号、群 ID、会话类型等），便于接收端获取 APNs - payload 的解析。

2. 当接收端收到 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 及以上版本支持推送消息覆盖，即后一条推送内容覆盖前面推送内容。

1. 在控制台首页 应用管理 中选择应用，然后单击 IM 即时通讯 下的 功能配置 按钮进入功能配置页。

   

2. 顶部选择 全局功能 页签，编辑 撤回消息覆盖策略。

   

   • 覆盖：撤回消息的推送会覆盖被撤回消息的原始推送。接收方仅显示 "xxx撤回了一条消息"（当前 vivo 推送不支持覆盖）
   • 不覆盖（默认）：撤回消息的推送不会覆盖被撤回消息的原始推送，接收方会收到被撤回消息和撤回通知两条推送

以撤回消息的场景为例：

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

相关参考

消息体的推送属性列表

云信 NIM SDK 通过 NIMMessage 类来定义消息体，其中关于推送的属性参数如下：

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