事件订阅 (在线状态)


云信允许用户订阅监听其他用户产生的事件,产生的事件的方式分为两种:

具体在线状态的业务逻辑可以参考 Demo 的 NTESSubscribeManager 实现。

发布自定义事件

@protocol NIMEventSubscribeManager <NSObject>
/**
 *  发布事件
 *
 *  @param event 需要广播的事件,事件可被其他人订阅
 *  @param completion 完成回调
 */
- (void)publishEvent:(NIMSubscribeEvent *)event
          completion:(NIMEventSubscribeBlock)completion;
@end

参数列表

参数 类型 说明
event NIMSubscribeEvent 需要广播的事件,事件可被其他人订阅
completion NIMEventSubscribeBlock 完成回调

在发布的前,需要自行构造出 NIMSubscribeEvent 对象,必须需要填写的字段为 type , valuetype 目前仅支持 “在线状态事件” , 即 NIMSubscribeSystemEventTypeOnline

NIMSubscribeEvent 对象原型

@interface NIMSubscribeEvent : NSObject

/**
 *  事件 Id, 发布时无需填写
 */
@property (nonatomic, copy, readonly) NSString *eventId;


/**
 *  事件发布者,发布时无须填写
 */
@property (nullable, nonatomic, copy, readonly) NSString *from;


/**
 *  事件发布的时间,发布时无须填写
 */
@property (nonatomic, assign, readonly) NSTimeInterval timestamp;


/**
 *  事件类型,1~99999 为云信保留类型,目前只支持预定义事件, 见 NIMSubscribeSystemEventType
 */
@property (nonatomic, assign) NSInteger type;


/**
 *  事件的状态值
 */
@property (nonatomic, assign) NSInteger value;


/**
 *  事件的有效期,范围为 60 秒到 7 天, 数值单位为秒,默认为 7 天
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 *  事件是否只广播给在线用户
 *  @discussion 默认为YES 如果这个值为NO,事件会在订阅者登录后同步
 */
@property (nonatomic, assign)  BOOL sendToOnlineUsersOnly;


/**
 *  事件是否支持多端同步
 *  @discussion 默认为YES。
 */
@property (nonatomic, assign)  BOOL syncEnabled;


/**
 *  订阅事件的额外信息,当订阅事件为 NIMSubscribeSystemEventTypeOnline 时,为 NIMSubscribeOnlineInfo
 */
@property (nonatomic, strong, readonly)  id subscribeInfo;

@end

属性列表

参数 类型 说明
eventId NSString 事件 Id, 发布时无需填写
from NSString 事件发布者,发布时无须填写
timestamp NSTimeInterval 事件发布的时间,发布时无须填写
from NSString 事件发布者,发布时无须填写
type NSInteger 事件类型,1~99999 为云信保留类型,目前只支持预定义事件, 见 NIMSubscribeSystemEventType
value NSInteger 事件的状态值
expiry NSTimeInterval 事件的有效期,范围为 60 秒到 7 天, 数值单位为秒,默认为 7 天
sendToOnlineUsersOnly BOOL 事件是否只广播给在线用户,默认为YES 如果这个值为NO,事件会在订阅者登录后同步
syncEnabled BOOL 事件是否支持多端同步, 默认为YES
subscribeInfo id 订阅事件的额外信息,当订阅事件为 NIMSubscribeSystemEventTypeOnline 时,为 NIMSubscribeOnlineInfo

订阅事件

@protocol NIMEventSubscribeManager <NSObject>
/**
 *  订阅事件
 *
 *  @param request 订阅请求
 *  @param completion 完成回调
 *  @discussion 请求中必需填写 type,expiry,publishers 字段
 */
- (void)subscribeEvent:(NIMSubscribeRequest *)request
            completion:(NIMEventSubscribeResponseBlock)completion;
@end

参数列表

参数 类型 说明
request NIMSubscribeRequest 订阅请求
completion NIMEventSubscribeResponseBlock 完成回调

取消订阅

@protocol NIMEventSubscribeManager <NSObject>
/**
 *  取消订阅事件
 *
 *  @param request 取消订阅请求
 *  @param completion 完成回调
 *  @discussion 请求中必须填写 type 字段 , 如果不填写 publishers 字段,则取消指定事件的全部订阅关系
 */
- (void)unSubscribeEvent:(NIMSubscribeRequest *)request
              completion:(NIMEventSubscribeResponseBlock)completion;
@end

参数列表

参数 类型 说明
request NIMSubscribeRequest 取消订阅请求
completion NIMEventSubscribeResponseBlock 完成回调

在调用 订阅/取消订阅 事件接口前,需要先构造 NIMSubscribeRequest 订阅请求对象。

NIMSubscribeRequest 原型

@interface NIMSubscribeRequest : NSObject

/**
 *  事件类型,1~99999 为云信保留类型,自定义的订阅事件请选择此范围以外的类型, 预定义事件定义见 NIMSubscribeSystemEventType
 */
@property (nonatomic, assign) NSInteger type;


/**
 *  订阅的有效期,范围为 60 秒到 30 天, 数值单位为秒, 超出时间则自动取消订阅,
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 *  订阅后是否立刻同步事件状态值
 *  @discussion 默认为NO,,如果填 YES ,则会收到事件回调 - (void)onRecvSubscribeEvent:
 */
@property (nonatomic, assign) BOOL syncEnabled;


/**
 *  发布事件者的 Id 数组,最多 100 个
 *  @discussion 由于同一个事件可能由不同的用户发出,只能订阅数组内用户发布的事件。
 */
@property (nonatomic, copy) NSArray *publishers;

@end

NIMSubscribeRequest 参数列表

参数 类型 说明
type NSInteger 事件类型,1~99999 为云信保留类型,自定义的订阅事件请选择此范围以外的类型, 预定义事件定义见 NIMSubscribeSystemEventType,可以使用自定义数值或者内置的枚举值
expiry NSTimeInterval 订阅的有效期,范围为 60 秒到 30 天, 数值单位为秒, 超出时间则自动取消订阅,
syncEnabled BOOL 订阅后是否立刻同步事件状态值,默认为NO,,如果填 YES ,则会收到事件回调 - (void)onRecvSubscribeEvent:
publishers NSArray 发布事件者的 Id 数组,最多 100 个,由于同一个事件可能由不同的用户发出,只能订阅数组内用户发布的事件。

在订阅事件中,订阅请求中必需填写 typeexpirypublishers 字段。publishers 字段最多仅支持 100 个账号 id , 某些场景如在线状态,订阅人数会超过限制,需要多次调用此接口来满足业务,具体详见 Demo 中 NTESSubscribeManager- (void)subscribeOnlineState 方法。

在取消订阅中,订阅请求中必须填写 type 字段,如果不填写 publishers 字段,则取消指定事件的全部订阅关系。

查询订阅事件关系

@protocol NIMEventSubscribeManager <NSObject>
/**
 *  查询订阅事件
 *
 *  @param request 查询请求
 *  @param completion 完成回调
 */
- (void)querySubscribeEvent:(NIMSubscribeRequest *)request
                 completion:(NIMEventSubscribeQueryBlock)completion;
@end

参数列表

参数 类型 说明
request NIMSubscribeRequest 取消订阅请求
completion NIMEventSubscribeQueryBlock 完成回调

SDK 提供查询本账号和指定账号存在的订阅关系接口,调用接口前,必须先构造 NIMSubscribeRequest 订阅请求对象。 其中,必须填写 type 字段 和 publishers 字段,查询人数最大支持 100 人。

目前不支持直接查询本账号和所有账号的订阅关系,上层需要维护好需要查询的用户 id, 通过多次调用此接口完成查询。