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

功能介绍

发送方 可在 发送 消息时配置消息体（V2NIMMessage）的推送属性，包括消息是否需要推送、推送文案、推送标题、是否强制推送等。

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

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

设置消息需要推送

发送方可以通过消息体中的是否需要推送参数（V2NIMMessage - pushConfig - pushEnabled），来设置该消息是否需要推送该消息。

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

设置推送文案

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

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

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

设置推送文案显示属性

可通过推送免打扰相关配置的 setDndConfig 方法来设置和获取推送文案显示属性 showDetail。

设置消息体的推送文案

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

发送设置好推送文案的消息后，接收方登录后会收到一条推送消息，内容形式为 "发送方昵称:"+"推送文案"。

其中，昵称为推送文案前缀（默认需要前缀），通过消息体中的是否需要推送前缀参数（V2NIMMessage - pushConfig - pushNickEnabled），来设置该消息是否需要推送文案前缀，云信服务器向第三方推送服务端请求推送时，前缀为用户昵称。

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

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

当您将消息接收方将推送文案属性设置为 不显示推送详情（V2NIMDndConfig.showDetail = false）：

• 优先显示提前设置好的自定义的推送文案，如何设置自定义推送文案，请参考以下步骤。
• 如果没有单独配置自定义的推送文案，那么将使用默认的推送文案：“你收到一条新消息”。

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

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

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

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

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

2. 设置自定义的推送文案类型。

   • Android：在初始化时，通过配置 SDKOptions.customPushContentType 来设置自定义的推送文案类型（对应控制台中的 自定义类型）。

     javaSDKOptions.customPushContentType = "custom_push_content_type"
     

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

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

   • HarmonyOS：在初始化时，通过配置 serviceOptions.pushServiceConfig.customPushContentType 来设置自定义的推送文案类型（对应控制台中的 自定义类型）。

     TypeScriptconst serviceOptions: NIMServiceOptions = {
         pushServiceConfig: {
             harmonyCertificateName: "DEMO_HMOS_PUSH", // 推送证书名
             customPushContentType: "CONTENT_TYPE_TEST" // NEW 推送文案配置
         }
     }
     

配置群消息强制推送/提醒

群消息的强制推送/提醒，具体请参考 群消息管理。

设置其他推送属性

其他推送属性，例如推送标题、推送铃声、推送通知栏跳转方式等，都通过 V2NIMMessage - pushConfig - pushPayload 来实现。

设置推送标题

发送方通过消息体的推送自定义字段 V2NIMMessage - pushConfig - pushPayload 来配置推送标题。

例如，配置 "pushTitle":"标题内容"，则以此显示（优先级最高）。推送 payload 具体请参考 推送 payload 配置。

如果没有配置，则使用云信默认的推送标题：点对点消息（P2P）推送标题默认为 用户昵称（如果没有设置用户昵称，则点对点消息推送标题默认为 新消息），群消息推送标题默认为 群名称。

设置推送铃声

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

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

覆盖通知栏内容

安卓和 iOS 10 及以上版本支持推送消息覆盖（除 vivo），即后一条推送内容覆盖前面推送内容。可以前往 云信控制台-选择对应的应用- IM 即时通讯 -功能配置- 基础功能 - 撤回消息覆盖策略-撤回消息是否覆盖原始消息推送 进行设置。

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

以撤回消息的场景为例：

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

推送角标未读数

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

设置消息计入未读数

可以通过自定义通知的配置项 V2NIMCustomNotification - notificationConfig - unreadEnabled 字段来设置该消息推送时是否要计入未读数。

设置角标未读数数值(iOS)

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)

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

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

消息体推送属性列表

V2NIMMessagePushConfig 接口说明：

名称	类型	是否必填	默认值	说明
pushEnabled	boolean	否	true	是否需要推送消息。
pushNickEnabled	boolean	否	true	是否需要推送消息发送方昵称。
pushContent	String	否	云信内置的推送文案	推送文案。
pushPayload	String	否	-	推送 Payload。
forcePush	boolean	否	false	是否忽略用户消息提醒相关设置，强制推送。 该字段仅对群消息有效。 该字段仅针对 forcePushAccountIds 中的用户。 默认为 false。如需要强制推送，需要设置为 true。
forcePushContent	String	否	pushContent	强制推送文案，若为空，则复用推送文案 pushContent。
forcePushAccountIds	List<String>	否	该会话全员	强制推送目标用户列表。若为空，则表示强制推送给该会话的所有成员。若不为空，最多可传入 100 个用户账号。