IM 即时通讯
Android
动态与公告
IM UIKit 更新日志
NIM SDK 开发版更新日志
NIM SDK 稳定版更新日志
新手接入指南
产品介绍
简介
主要功能
产品优势
功能介绍
账号集成与登录
多端登录与互踢策略
群组功能
聊天室功能
聊天室标签功能
圈组功能
质量数据监控台
海外数据中心
IM平滑迁移方案
接口及业务限制
体验 Demo
下载 SDK 与 Demo 源码
快速开始
跑通 IM Demo 源码
实现单聊消息收发(不含 UI)
跑通圈组 Demo 源码
实现圈组消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能概览
快速集成 IM UIKit
组件导入
初始化
界面跳转
自定义用户信息
全局配置
会话列表相关
集成会话列表界面
会话列表事件监听
自定义会话列表界面 UI
会话列表 API 概览
会话消息相关
集成会话界面
会话界面事件监听
实现音视频通话
实现地理位置消息功能(含 UI)
实现自定义消息发送(含 UI)
自定义会话界面 UI
会话消息 API 概览
通讯录相关
集成通讯录界面
自定义通讯录界面 UI
通讯录界面事件监听
通讯录 API 概览
UIKit 功能实现方案
消息回复实现方案
UIKit 版本升级说明
系统兼容相关
IM UIKit 常见问题排查
IM UIKit API 概览
不含 UI 集成
使用说明
集成 SDK
初始化
登录相关
登录 IM
多端登录与互踢
登出 IM
消息相关
消息概述
消息收发
自定义消息收发
消息配置选项
NOS 存储场景
广播消息收发
消息已读回执
消息撤回
消息重发与转发
消息更新
消息过滤
语音消息处理
插入本地消息
历史消息
最近会话
服务端会话服务
用户资料
用户关系
在线状态订阅
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
Android 离线推送
实现离线推送
配置消息的推送属性
设置群消息强制推送
设置推送全局免打扰
设置多端推送策略
集成小米推送
集成华为推送
集成荣耀推送
集成 OPPO 推送
集成 vivo 推送
集成魅族推送
集成谷歌推送(FCM)
消息提醒
实现消息提醒
配置消息提醒功能
设置群消息强制提醒
设置消息提醒文案
定制通知栏显示信息
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
聊天室
圈组功能
圈组概述
登录管理
服务器相关
服务器概述
服务器管理
服务器成员管理
游客功能
服务器未读数管理
频道相关
频道概述
频道管理
频道黑白名单
实时互动频道
频道分组
频道分组黑白名单
频道未读数管理
搜索服务器和频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
用户定制权限
频道分组身份组
自定义权限项
成员权限查询与判定
身份组相关查询
圈组订阅机制
圈组消息相关
图解圈组消息流转
圈组消息收发
消息发送配置项
圈组消息撤回
圈组消息更新
圈组消息删除
消息正在输入
会话消息回复(Thread)
圈组快捷评论
获取频道最后一条消息
查询历史消息
查询@我的消息
圈组消息缓存
圈组消息搜索
圈组系统通知相关
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组离线推送
圈组内容审核
圈组相关抄送
圈组第三方回调
圈组各端接口命名差异
反垃圾(内容审核)
聊天扩展
接入第三方机器人
其他
最佳实践
IM 登录最佳实践
IM 应用隐私合规
聊天室重要消息投递
API 参考
Android SDK API
Android SDK 状态码/错误码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
开通聊天室功能
配置应用客户端标识
添加推送证书
常见问题
FAQ
错题集
Android 端推送问题排查
第三方推送厂商的限制说明
服务协议

圈组离线推送

更新时间: 2023/04/11 19:31:44

圈组支持接收方在个人使用的多个维度(设备、圈组服务器、频道分组和频道)配置需要接收的推送消息类型,也支持发送方在发消息时决定该消息是否需要推送并配置该消息的推送文案。

NIM SDK 的 QChatPushService接口类提供了设备维度的圈组推送服务接口,QChatServerService接口类提供圈组服务器维度的推送配置方法,QChatChannelService接口类提供频道分组维度和频道维度的推送配置方法。

功能介绍

圈组根据消息优先级和推送范围的大小确定消息是否离线推送,具体推送机制见下图。

上图中,推送消息被分为高中低优先级三种类型:

  • 高优先级消息:@某些人等(有具体目标、有@意愿)。
  • 中优先级消息:@所有人等(没有具体目标、有@意愿)。
  • 低优先级消息:普通消息等(没有具体目标、没有@意愿)。

NIM SDK 支持通过QChatPushMsgType枚举设置需要接收的推送消息类型,具体枚举值如下:

枚举值
说明
ALL 接收全部类型的推送消息
HIGH_LEVEL 只接收高优先级的推送消息
HIGH_MID_LEVEL 只接收高优先级和中优先级的推送消息
INHERIT 继承用户个人使用的上一维度的推送消息类型配置,具体维度从上到下为设备维度、服务器维度、频道分组维度和频道维度。例如,如果服务器维度的推送消息类型设置为ALL的情况下,频道分组维度的推送消息类型设置为INHERIT,那么频道分组维度的推送消息类型实际也为ALL,即接收全部类型的推送消息。
NONE 全部推送消息都不接收

需要接收的推送消息类型可在用户个人使用的不同维度配置,包括设备维度、服务器维度、频道分组维度和频道维度。

  • 如果多个维度同时配置了推送消息类型,最终生效的推送消息类型取决于维度的优先级。

    不同维度的优先级为频道>频道分组>服务器>设备。最终实际生效的推送消息类型,为 最高优维度 的配置。

  • 圈组在设备维度的推送消息类型默认为接收全部类型的推送消息ALL),在其他维度的推送消息类型默认为继承上一维度的推送消息类型配置INHERIT)。具体的“继承”示例,可参见本文末尾的常见问题

  • 服务器成员数大于或等于 2000 人阈值时,即使接收方将推送消息类型设置为“接收全部类型的消息推送”(ALL),也无法收到低优先级消息的离线推送。
  • 如果接收方离线而且消息不走离线推送,接收方可通过查询历史消息的方式获取离线消息。

前提条件

在实现圈组的离线推送前,请确保:

  • 已了解消息被推送前的流转过程,具体参见图解圈组消息流转
  • 已在集成 SDK 时集成推送辅助包(关键字:push),具体参见集成 SDK
  • 已在初始化时完成 Android 厂商推送相关基础配置,具体参见实现 Android 离线推送的步骤1 至步骤 3。

实现圈组消息推送

实现圈组消息推送的流程如下图所示。

下图可能因为网络问题而显示异常。如显示异常,一般刷新当前页面即可正常显示。

uml diagram

步骤1:开启第三方推送服务

接收方确认未关闭圈组的第三方推送服务。圈组的第三方推送服务默认开启

如需要关闭圈组的第三方推送服务,接收方可调用enable方法关闭。

//开启圈组推送
NIMClient.getService(QChatPushService.class).enable(true).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        //开启圈组推送成功
    }

    @Override
    public void onFailed(int code) {
        //开启圈组推送失败,返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //开启圈组推送异常
    }
});

步骤2:配置圈组推送选项

接收方开启圈组的第三方推送服务后,还可按需配置其他选项,包括推送免打扰、推送不展示文案详情、需要接收的推送消息类型等。

圈组推送免打扰

调用setPushNoDisturbConfig方法可以设置是否开启圈组推送免打扰(若开启,默认免打扰时段为 22:00-08:00),以及设置免打扰时间段。如果设置了免打扰时间,则在该时间段内将不再收到推送。

  • 圈组推送免打扰默认不开启。
  • 可调用observePushNoDisturbConfigUpdate方法注册推送免打扰配置更新观察者,监听圈组的免打扰配置更新事件通知。

示例代码如下:

//设置圈组推送免打扰时间,设置0点到8点30分之间不发推送信息
NIMClient.getService(QChatPushService.class).setPushNoDisturbConfig(true,"00:00","08:30").setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        //设置圈组推送免打扰时间成功
    }

    @Override
    public void onFailed(int code) {
        //设置圈组推送免打扰时间失败,返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //设置圈组推送免打扰时间异常
    }
});

圈组推送是否不展示详情

调用setPushShowNoDetail方法,可设置圈组推送消息是否不展示文案详情。如果不展示详情,默认的推送文案为“你收到一条新消息”。


示例代码如下:

NIMClient.getService(QChatPushService.class).setPushShowNoDetail(true).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        //设置圈组推送是否不展示详情成功
    }

    @Override
    public void onFailed(int code) {
        //设置圈组推送是否不展示详情送失败,返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //设置圈组推送是否不展示详情异常
    }
});

设备维度的推送消息类型

调用setPushMsgType方法设置需要接收的推送消息类型(设备维度)。 示例代码如下:

NIMClient.getService(QChatPushService.class).setPushMsgType(QChatPushMsgType.ALL).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        //设置成功
    }

    @Override
    public void onFailed(int code) {
        //设置失败,返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //设置异常
    }
});
冗余接口,先隐藏

获取圈组推送配置

  • 调用setPushConfig方法可对圈组推送做整体配置。

    该方法的参数在QChatPushConfigParam类中定义,参数说明如下:

    参数 类型 说明
    isPushShowNoDetail Boolean 推送是否不显示详情
    isNoDisturbOpen Boolean 是否开启免打扰
    startNoDisturbTime String 免打扰开始时间,格式 HH:mm
    stopNoDisturbTime String 免打扰结束时间,格式 HH:mm
    pushMsgType QChatPushMsgType 消息推送类型选项
    QChatPushConfigParam param = new QChatPushConfigParam(false,true,"22:00","08:00", QChatPushMsgType.ALL);
    NIMClient.getService(QChatPushService.class).setPushConfig(param).setCallback(new RequestCallback<Void>() {
        @Override
        public void onSuccess(Void param) {
            //设置成功
        }
    
        @Override
        public void onFailed(int code) {
            //设置失败,返回错误code
        }
    
        @Override
        public void onException(Throwable exception) {
            //设置异常
        }
    });
    

调用getPushConfig获取当前设备圈组推送配置,包括推送是否不显示详情、是否开启免打扰和推送消息类型等。

/**
* 获取圈组推送设置
*
* @return QChatPushConfig
*/
QChatPushConfig getPushConfig();

服务器维度的推送消息类型

调用updateUserServerPushConfig方法更新某个服务器下需要接收的推送消息类型。

  • 服务器维度的推送消息类型默认为INHERIT,即继承设备维度的推送消息类型配置。
  • 具体的更新配置示例,参见本文末尾的常见问题

示例代码如下:

NIMClient.getService(QChatServerService.class).updateUserServerPushConfig(new QChatUpdateUserServerPushConfigParam(1607312, QChatPushMsgType.ALL))
                .setCallback(new RequestCallback<Void>() {
                    @Override
                    public void onSuccess(Void param) {
                        //操作成功
                    }

                    @Override
                    public void onFailed(int code) {
                        //操作失败,返回错误code
                    }

                    @Override
                    public void onException(Throwable exception) {
                        //操作异常
                    }
                });

频道分组维度的推送消息类型

调用updateUserChannelCategoryPushConfig方法更新在某个频道分组下需要接收的推送消息类型。

示例代码如下:

long serviceId = 2114708;
long categoryId = 17790;
//设置推送之接收高等级消息: @某些人等(有具体目标、有@意愿)
QChatPushMsgType pushMsgType = QChatPushMsgType.HIGH_LEVEL;
QChatUpdateUserChannelCategoryPushConfigParam pushConfigParam = new QChatUpdateUserChannelCategoryPushConfigParam(serviceId,categoryId,pushMsgType)
NIMClient.getService(QChatChannelService.class).updateUserChannelCategoryPushConfig(pushConfigParam).setCallback(
        new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                //更新用户频道分组推送配置成功
            }

频道维度的推送消息类型

调用updateUserChannelPushConfig方法更新在某个频道下需要接收的推送消息类型。

  • 频道维度的推送消息类型默认为INHERIT,即继承上一维度(服务器维度或频道分组维度)的推送消息类型配置。
  • 具体的更新配置示例,参见本文末尾的常见问题

示例代码如下:

NIMClient.getService(QChatChannelService.class).updateUserChannelPushConfig(new QChatUpdateUserChannelPushConfigParam(1607312, 1492446L,QChatPushMsgType.ALL))
                .setCallback(new RequestCallback<Void>() {
                    @Override
                    public void onSuccess(Void param) {
                        //操作成功
                    }

                    @Override
                    public void onFailed(int code) {
                        //操作失败,返回错误code
                    }

                    @Override
                    public void onException(Throwable exception) {
                        //操作异常
                    }
                });

步骤3:发消息时配置推送

发送方调用sendMessage方法发送某条消息时,或调用sendSystemNotification方法发送自定义系统通知时,确认其内置方法setPushEnable设置为 true,即该消息需要推送。

setPushEnable默认为 true,即圈组的消息默认需要推送。


发送方发消息或自定义系统通知时还可配置如下选项:

内置方法
说明
isNeedPushNick 是否需要推送昵称,默认为用户昵称
setPushContent 设置推送文案,长度限制 500 字符,撤回消息时该字段无效
setPushPayload 设置推送的 payload 进行自定义配置,例如可通过设置消息体QChatMessage的 payload 实现点击通知栏跳转至目标界面(相关说明参考推送通知栏跳转)。长度限制 2000 字符,撤回消息时该字段无效

获取圈组推送配置

接收方配置了上文提及的圈组推送选项后,在其他设备端登录时,可按需调用如下方法获取相应的配置。

获取是否已开启第三方推送

调用isEnable方法,判断是否已经开启了圈组的第三方推送服务。

获取圈组推送免打扰配置

调用getPushNoDisturbConfig方法获取免打扰时间设置。

/**
* 获取圈组推送免打扰设置
*
* @return NoDisturbConfig
*/
NoDisturbConfig getPushNoDisturbConfig();

获取推送是否不展示详情

调用isPushShowNoDetail方法判断圈组推送是否不展示文案详情。

/**
* 获取圈组推送是否不展示详情
*
* @return 当前是否不展示详情
*/
boolean isPushShowNoDetail();

获取设备维度的推送消息类型

调用getPushMsgType获取在设备维度需要接收的推送消息类型的配置。

/**
* 获取推送消息类型
* @return
*/
QChatPushMsgType getPushMsgType();

获取服务器维度的推送配置列表

调用getUserServerPushConfigs方法查询多个服务器的推送配置列表。

单次调用最多可传入 10 个服务器 ID 进行查询。

示例代码如下:

List<Long> serverIdList = getServerIdList();
NIMClient.getService(QChatServerService.class).getUserServerPushConfigs(new QChatGetUserServerPushConfigsParam(serverIdList))
        .setCallback(new RequestCallback<QChatGetUserPushConfigsResult>() {
            @Override
            public void onSuccess(QChatGetUserPushConfigsResult result) {
                //操作成功
                List<QChatUserPushConfig> userPushConfigs = result.getUserPushConfigs();
            }

            @Override
            public void onFailed(int code) {
                //操作失败,返回错误code
            }

            @Override
            public void onException(Throwable exception) {
                //操作异常
            }
        });

获取频道分组维度的推送配置列表

调用getUserChannelCategoryPushConfigs获取多个频道分组的推送配置列表。

单次调用最多可传入 10 个频道分组 ID 进行查询。

示例代码如下:

long serviceId = 2114708;
long categoryId = 17790;
List<QChatChannelCategoryIdInfo> channelCategoryIdInfos = new ArrayList<>();
channelCategoryIdInfos.add(new QChatChannelCategoryIdInfo(serviceId,categoryId));
QChatGetUserChannelCategoryPushConfigsParam getUserChannelCategoryPushConfigsParam = new QChatGetUserChannelCategoryPushConfigsParam(channelCategoryIdInfos);
NIMClient.getService(QChatChannelService.class).getUserChannelCategoryPushConfigs(getUserChannelCategoryPushConfigsParam).setCallback(
        new RequestCallback<QChatGetUserPushConfigsResult>() {
            @Override
            public void onSuccess(QChatGetUserPushConfigsResult result) {
                //获取查询到的用户推送配置列表
                List<QChatUserPushConfig> userPushConfigs = result.getUserPushConfigs();
            }

            @Override
            public void onFailed(int code) {
                //查询失败
            }

            @Override
            public void onException(Throwable exception) {
                //查询异常
            }
        });

获取频道维度的推送配置列表

调用getUserChannelPushConfigs获取多个频道的推送配置列表。

单次调用最多可传入 10 个频道 ID 进行查询。

示例代码如下:

List<QChatChannelIdInfo> channelIdInfos = getChannelIdInfos();
NIMClient.getService(QChatChannelService.class).getUserChannelPushConfigs(new QChatGetUserChannelPushConfigsParam(channelIdInfos))
        .setCallback(new RequestCallback<QChatGetUserPushConfigsResult>() {
            @Override
            public void onSuccess(QChatGetUserPushConfigsResult result) {
                //操作成功
                List<QChatUserPushConfig> userPushConfigs = result.getUserPushConfigs();
            }

            @Override
            public void onFailed(int code) {
                //操作失败,返回错误code
            }

            @Override
            public void onException(Throwable exception) {
                //操作异常
            }
        });

常见问题

1. 如何实现不接收某个服务器的离线消息推送?

调用updateUserServerPushConfig方法时,通过serverId指定需要静默的服务器的 ID,并将pushMsgType设置为NONE。调用成功后,该用户将不再接收指定服务器的离线消息推送。

2. 如何实现只接收某个服务器的高优离线消息推送?

用户首次配置圈组的离线消息推送时,按照如下步骤配置即可:

  1. 调用setPushMsgType方法,调用时将pushMsgType设置为NONE

    本步骤完成后,用户个人使用的设备维度和服务器维度的推送消息类型配置,具体如下:

    用户个人使用的维度 推送消息类型 实际生效 说明
    设备 NONE NONE 当前设备不接收圈组内所有推送消息
    服务器 默认为INHERIT NONE 继承设备维度的配置,即“不接收服务器维度的所有推送消息”
  2. 调用updateUserServerPushConfig方法更新服务器的推送消息配置,调用时完成如下配置:

    参数
    说明
    serverId 指定服务器的 ID,假设此处指定的服务器为服务器A
    pushMsgType 设置为HIGH_LEVEL

    本步骤完成后,用户个人使用的设备维度和服务器维度的推送消息类型配置,具体如下:

    用户个人使用的维度 推送消息类型 实际生效 说明
    设备 NONE NONE 当前设备不接收圈组内所有推送消息
    其他服务器 仍为INHERIT NONE 继承设备维度的配置,即“不接收服务器维度的所有推送消息”
    服务器A HIGH_LEVEL HIGH_LEVEL 只接收服务器A 内的“@消息”等高优先级的推送消息

3. 如何实现不接收某个频道的离线消息推送?

调用updateUserChannelPushConfig方法,调用时通过serverId指定频道所属的服务器的ID,并将pushMsgType设置为NONE。调用成功后,该用户将不再接收指定频道的所有离线消息推送。

4. 如何实现只接收某个频道的高优先级离线消息推送?

用户首次配置圈组的离线消息推送时,按照如下步骤配置即可:

  1. 调用setPushMsgType方法更新设备维度的推送消息类型配置,调用时将pushMsgType设置为NONE

    本步骤完成后,用户个人使用的各个维度的推送消息类型配置,具体如下:

    用户个人使用的维度 推送消息类型 实际生效 说明
    设备 NONE NONE 当前设备不接收圈组内所有推送消息
    服务器 默认为INHERIT NONE 继承设备维度的配置,即在频道所属的服务器“不接收所有推送消息”
    频道分组 默认为INHERIT NONE 继承服务器维度的配置,即在频道所属的频道分组“不接收所有推送消息”
    频道 默认为INHERIT NONE 继承频道分组维度的配置,即在频道“不接收所有推送消息” 如果无频道分组,则将直接继承服务器维度的配置。
  2. 调用updateUserChannelPushConfig方法,调用时完成如下配置:

    参数
    说明
    serverId 指定频道所属的服务器的 ID
    channelId 指定需要接收高优推送消息的频道的 ID,假设此处指定的为频道A
    pushMsgType 设置为HIGH_LEVEL

    本步骤完成后,用户个人使用的各个维度的推送消息类型配置,将如下表所示:

    用户个人使用的维度
    推送消息类型
    实际生效
    说明
    设备 NONE NONE 当前设备不接收圈组内所有推送消息
    服务器 仍为INHERIT NONE 继承设备维度的配置,即在频道所属的服务器“不接收所有推送消息”
    频道分组 仍为INHERIT NONE 继承服务器维度的配置,即在频道所属的频道分组“不接收所有推送消息”
    频道A HIGH_LEVEL HIGH_LEVEL 只接收频道A 内的“@消息”等高优先级的推送消息
    服务器的其他频道 仍为INHERIT NONE 继承服务器维度的配置,即“不接收频道内所有推送消息”
此文档是否对你有帮助?
有帮助
我要吐槽
  • 功能介绍
  • 前提条件
  • 实现圈组消息推送
  • 步骤1:开启第三方推送服务
  • 步骤2:配置圈组推送选项
  • 圈组推送免打扰
  • 圈组推送是否不展示详情
  • 设备维度的推送消息类型
  • 服务器维度的推送消息类型
  • 频道分组维度的推送消息类型
  • 频道维度的推送消息类型
  • 步骤3:发消息时配置推送
  • 获取圈组推送配置
  • 获取是否已开启第三方推送
  • 获取圈组推送免打扰配置
  • 获取推送是否不展示详情
  • 获取设备维度的推送消息类型
  • 获取服务器维度的推送配置列表
  • 获取频道分组维度的推送配置列表
  • 获取频道维度的推送配置列表
  • 常见问题
  • 1. 如何实现不接收某个服务器的离线消息推送?
  • 2. 如何实现只接收某个服务器的高优离线消息推送?
  • 3. 如何实现不接收某个频道的离线消息推送?
  • 4. 如何实现只接收某个频道的高优先级离线消息推送?