事件订阅 (在线状态)

用户可以通过事件发布及订阅,来实现"发布-订阅"的设计模式编程方法。可应用于订阅指定用户在线状态、用户个性化信息订阅等场景。
目前,仅开放类型type=1的事件订阅,用户可自定义value值(一个value对应一个事件状态,1-9999为云信预定义值,开发者不可使用)来实现自身业务需求。
大致流程为:A订阅B——>B发布某一特定的事件——>A监听来自B的该事件状态变更——>按照自身业务逻辑解析处理。
注意:云信系统内置的在线状态事件(type=1,value=1/2/3)无需主动发布,这一工作将由云信服务器托管。

订阅事件

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

参数列表

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

NIMSubscribeRequest 原型

@interface NIMSubscribeRequest : NSObject

/**
 *  事件类型,传1即可。
 */
@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

取消订阅

取消当前的订阅。

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

参数列表

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

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

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

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

发布事件

@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。
 */
@property (nonatomic, assign) NSInteger type;


/**
 *  事件的状态值。value为10000及以上(1-9999为云信预定义值,开发者不可使用)。
 */
@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

监听所订阅的事件

当订阅的事件从云信服务器下推时,可从-onRecvSubscribeEvents回调监听。 请实现NIMEventSubscribeManagerDelegate协议的 –onRecvSubscribeEvents: 方法。

原型

@protocol NIMEventSubscribeManagerDelegate <NSObject>
/**
 *  收到所订阅的事件的回调
 *  @param events 广播的事件 NIMSubscribeEvent 列表
 */
- (void)onRecvSubscribeEvents:(NSArray *)events;
@end

查询订阅事件关系

@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, 通过多次调用此接口完成查询。

在线状态事件

在线状态(在线、异常断开、登出)为云信系统内置事件,只需向销售发起申请,申请成功后,即可使用。无需主动发布事件状态。典型的应用场景为A订阅了B的在线状态事件,则当A登录成功后,可以即时获取B此时的在线状态:在线、异常断开或是登出状态。

注意事项:

如前所述,在线状态事件为云信系统内置事件,无需开发者主动发布。在A订阅了B的type=1事件后,当A登录时,若B此时在线,则会收到对应的事件;若后续B再登录上线时,且A也在线,则依旧可以监听到。 具体在线状态的业务逻辑可以参考 Demo 的 NTESSubscribeManager 实现。