iOS

配置消息的推送属性

更新时间: 2024/08/08 11:21:49

云信 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 即时通讯 下的 功能配置 按钮进入功能配置页。

    image.png
  2. 顶部选择 基础功能 页签,开启 自定义推送

    开启自定义推送.png

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

    新增自定义推送文案.png

    最多可以配置 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 即时通讯 下的 功能配置 按钮进入功能配置页。

    image.png
  2. 顶部选择 基础功能 页签,编辑 iOS 应用角标未读数上限

    角标未读数.png

设置推送标题

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

  • 方式一:通过设置消息体 NIMMessage - apnsPayload - apsField - alert中的 titlebody 字段可以指定推送标题与推送文案,优先级最高。

    如配置了apsFieldalert 字段,但是 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 得到 sessionidsessiontype,并跳转到对应的界面。

示例代码如下:

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

覆盖通知栏内容

iOS 10 及以上版本支持推送消息覆盖,即后一条推送内容覆盖前面推送内容。

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

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

    消息撤回不覆盖.png

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

以撤回消息的场景为例:

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

相关参考

消息体的推送属性列表

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

参数 类型 说明
setting NIMMessageSetting 消息配置项
其中 apnsEnabled 表示消息是否需要推送;apnsWithPrefix 表示推送是否需要带前缀(一般为昵称);shouldBeCounted 表示该消息推送时是否要计入角标未读数
apnsMemberOption NIMMessageApnsMemberOption 指定成员推送选项,包括是否强制推送,指定需要特殊推送的用户
通过该选项进行一些更复杂的推送设定,目前只能在群会话中使用
apnsContent NSString* 推送文案,最大长度 500 字符,撤回消息时该字段无效
apnsPayload NSDictionary* 消息的推送 payload,可以通过该字段自定义消息推送 payload,支持字段参考苹果技术文档,最大长度 2018 字符,撤回消息时该字段无效
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 设置消息需要推送
  • 群消息强制推送
  • 设置推送文案
  • 设置消息体的推送文案
  • 使用不显示详情的自定义推送文案
  • 推送角标未读数
  • 设置消息计入角标未读数
  • 设置角标未读数数值
  • 设置推送标题
  • 设置推送铃声
  • 设置推送通知栏
  • 实现点击通知栏跳转
  • 覆盖通知栏内容
  • 相关参考
  • 消息体的推送属性列表