IM 即时通讯
Android
开发指南

圈组订阅机制

更新时间: 2024/01/03 10:34:57

一般情况下,圈组内消息与系统通知的接收受订阅机制限制。云信 IM 为圈组功能提供两种订阅方式:自动订阅和手动订阅,您可以根据业务需求进行选择。

订阅模式 描述 频道数上限
自动订阅 当用户登录到圈组服务器后,无需手动订阅服务器或频道,进入服务器或频道时即可收到消息、事件和系统通知,退出时则自动取消订阅。 10000
手动订阅 当用户登录到圈组服务器后,需要先订阅相关服务器或频道,才能收到相关频道和服务器的消息、事件和系统通知,退出时手动取消订阅。

本文仅介绍服务器成员的订阅机制。自 v9.8.0起,圈组支持游客订阅服务器和频道,从而实现游客接收消息和部分系统通知,游客的订阅机制与服务器成员的订阅机制互相独立。游客订阅相关说明,请参见游客功能

免除订阅的情况

下列条件下,服务器或频道的成员接收消息和系统通知不受订阅机制限制:

  • 成员数量小于 2,000 (可通过云信官网首页提供的联系方式咨询商务经理调整该阈值)的服务器,即使不订阅,其成员也能收到这些服务器和服务器下所有频道的消息和系统通知。
  • 被@的账号(非@所有人),即使没有订阅也会收到消息。
  • 针对某些成员发送的系统通知(区别于发送给频道内所有人或者服务器内所有人),即使没有订阅这些成员也会收到通知。

自动订阅

开启自动订阅

在应用的 Application#onCreate 中,调用 NIMClient#init 方法进行初始化时,配置圈组自动订阅参数 SDKOptions#auto_subscribetrue

示例代码:

public class NimApplication extends Application {

	public void onCreate() {
		// ... your codes

		// SDK初始化(启动后台服务,若已经存在用户登录信息, SDK 将进行自动登录)。不能对初始化语句添加进程判断逻辑。
		NIMClient.init(this, loginInfo(), options());

		// ... your codes

        // 使用 `NIMUtil` 类可以进行主进程判断。
        // boolean mainProcess = NIMUtil.isMainProcess(context)
		if (NIMUtil.isMainProcess(this)) {
			// 注意:以下操作必须在主进程中进行
            // 1、UI相关初始化操作
            // 2、相关Service调用
        }
	}

	// 如果提供,将同时进行自动登录。如果当前还没有登录用户,请传入null。详见自动登录章节。
    private LoginInfo loginInfo() {
	    return null;
	}

	// 设置初始化配置参数,如果返回值为 null,则全部使用默认参数。
	private SDKOptions options() {
		SDKOptions options = new SDKOptions();
        ...
	    // 开启圈组自动订阅,默认为 false
	    options.auto_subscribe = true;
        ...

	    return options;
	}
}

订阅类型

自动订阅包含以下订阅类型:

维度
订阅类型
订阅后接收的信息
服务器 订阅所在服务器的系统通知,单用户默认最多可订阅 2000 个服务器 服务器相关系统通知,如服务器基本信息修改、人员进出、权限变更、创建频道等
频道 订阅所在频道的消息和系统通知,单用户默认最多可订阅 100 个频道。 频道的消息和频道相关系统通知。
频道 订阅所在频道的消息未读数和系统通知,单用户默认最多可订阅 500 个频道。 频道的未读数(默认上限 99)和频道相关系统通知
频道 订阅所在频道的消息未读状态和系统通知,单用户默认最多可订阅 1000 个频道。 频道的未读状态和频道相关系统通知。未读状态仅区分未读数为 0 和未读数大于 0 两种情况

订阅限制

自动订阅有以下限制:

  • 自动订阅不包含服务器或频道的“消息正在输入”事件,您需要手动订阅该事件。
  • 自动订阅频道数上限为 10000,如果圈组内频道数超过该值,请使用手动订阅。

手动订阅

订阅圈组服务器

服务器成员调用subscribeServer方法即可订阅圈组服务器。该方法的入参结构QChatSubscribeServerParam中需传入订阅类型(具体见下文的订阅类型),订阅操作类型(订阅或取消订阅)和需要订阅的serverId列表。

注意的是,调用该方法时可传入的订阅类型枚举值,仅能为SERVER_MSG,即订阅服务器的消息和服务器相关系统通知,如server基本信息修改、人员进出、权限变更、创建频道等。

  • 用户所参与事件(即为事件当事人)的系统通知,如被邀请加入服务器、被踢出服务器等,用户不需要订阅也能收到。
  • 用户未参与事件的系统通知,在服务器人数大于默认阈值(2000 人)(即“大服务器”)时,需要用户订阅服务器后,才能收到。如服务器人数小于默认阈值(即“小服务器”),用户不订阅服务器,也能收到这类系统通知。

示例代码:

QChatSubscribeServerParam param = new QChatSubscribeServerParam(QChatSubscribeType.SERVER_MSG, QChatSubscribeOperateType.SUB, getServerList());

NIMClient.getService(QChatServerService.class).subscribeServer(param).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        //订阅成功
    }

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

    @Override
    public void onException(Throwable exception) {
        //订阅异常
    }
});

订阅频道

服务器成员调用subscribeChannel方法即可订阅频道。该方法的入参结构为QChatSubscribeChannelParam,需传入需要传入订阅类型(具体见下文的订阅类型)、订阅操作类型(订阅或取消订阅)和待订阅的serverId+channelId列表。

示例代码:

    List<QChatChannelIdInfo> channelIdInfos = new ArrayList<>();
    channelIdInfos.add(new QChatChannelIdInfo(943445L,885305L));
    //订阅channel的【消息未读数】/【通知】
    QChatSubscribeChannelParam param = new QChatSubscribeChannelParam(QChatSubscribeType.CHANNEL_MSG_UNREAD_COUNT, QChatSubscribeOperateType.SUB, channelIdInfos);

    NIMClient.getService(QChatChannelService.class).subscribeChannel(param).setCallback(new RequestCallback<QChatSubscribeChannelResult>() {
        @Override
        public void onSuccess(QChatSubscribeChannelResult result) {
            //订阅成功,返回订阅Channel的未读信息
            List<QChatUnreadInfo> unreadInfoList = result.getUnreadInfoList();
        }

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

        @Override
        public void onException(Throwable exception) {
            //订阅异常
        }
    });

订阅类型

QChatSubscribeType 枚举定义了圈组服务器和频道的订阅类型。各订阅类型说明如下:

同一个频道(channelId),同时只能订阅其中一种频道订阅类型,若一个频道同时订阅多种类型,则以最后订阅的类型为准。

枚举值
维度
订阅类型
订阅后接收的信息
SERVER_MSG(1) 服务器 订阅某个服务器的系统通知,单用户默认最多可订阅 2000 个服务器 服务器相关系统通知,如服务器基本信息修改、人员进出、权限变更、创建频道等
CHANNEL_MSG(2) 频道 订阅某个频道的消息和系统通知,单用户默认最多可订阅 100 个频道。 频道的消息和频道相关系统通知。
CHANNEL_MSG_UNREAD_COUNT(3) 频道 订阅某个频道的消息未读数和系统通知,单用户默认最多可订阅 500 个频道。 频道的未读数(默认上限 99)和频道相关系统通知
CHANNEL_MSG_UNREAD_STATUS(4) 频道 订阅某个频道的消息未读状态和系统通知,单用户默认最多可订阅 1000 个频道。 频道的未读状态和频道相关系统通知。未读状态仅区分未读数为 0 和未读数大于 0 两种情况
CHANNEL_MSG_TYPING(5) 频道 订阅某个频道的“消息正在输入”事件,单用户默认最多可订阅 100 个频道 “消息正在输入”事件信息
注意:该事件信息的接收,不受服务器人数阈值的影响,即无论服务器人数是否超过阈值,用户都需要先订阅该事件,才能接收到事件信息。在频道界面上显示“消息正在输入”的实现流程,请参见消息正在输入

注意事项

已开启自动订阅的前提下,调用手动订阅方法并设置订阅类型为 CHANNEL_MSG_TYPING(5) 之外的任意一项,则返回 403 或 10403 错误码,报错信息如下:

[QChat] subscribe server failed, manual subscribe is not allowed in auto subscribe mode.
[QChat] subscribe channel failed, manual subscribe is not allowed in auto subscribe mode.

因此,如果要将自动订阅模式切换为手动订阅,您需要先关闭自动订阅模式(SDKOptions#auto_subscribefalse),再调用手动订阅模式相关接口。

此文档是否对你有帮助?
有帮助
去反馈
  • 免除订阅的情况
  • 自动订阅
  • 开启自动订阅
  • 订阅类型
  • 订阅限制
  • 手动订阅
  • 订阅圈组服务器
  • 订阅频道
  • 订阅类型
  • 注意事项