功能概述

用户可以通过事件发布及订阅，来实现"发布-订阅"的设计模式编程方法。可应用于订阅指定用户在线状态、用户个性化信息订阅等场景。

目前，仅开放类型type=1的事件订阅，用户可自定义value值（一个value对应一个事件状态，1-9999为云信预定义值，开发者不可使用）来实现自身业务需求。

大致流程为：A订阅B——>B发布自定义事件——>A监听来自B的该事件状态变更——>按照自身业务逻辑解析处理。

注意：云信系统内置的在线状态事件(type=1,value=1/2/3)无需主动发布，这一工作将由云信服务器托管。

前提条件

在线状态订阅功能需要额外在云信控制台开通。

开通路径：应用管理 > 产品功能 > IM 即时通讯 > 全局功能 > 在线状态订阅

订阅事件

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

参数列表

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

NIMSubscribeRequest 原型

objc@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

取消订阅

取消当前的订阅。

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

参数列表

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

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

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

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

发布自定义事件

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

参数列表

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

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

NIMSubscribeEvent 对象原型

objc@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: 方法。

原型

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

查询订阅事件关系

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

在线状态事件

在线状态（在线、异常断开、登出）为云信系统内置事件，支持用户订阅其他用户的在线状态事件，当登录成功后，可以即时获取订阅用户此时的在线状态，包括在线、异常断开或是登出状态。

使用在线状态订阅功能前，您需要在云信控制台开启该功能：

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

   

2. 在顶部选择基础功能页签，开启在线状态订阅。

   

注意事项：

• 每次调用接口最多只能订阅100个账号，数量较多需多次调用。在线状态事件订阅，每个accid最大有效订阅账号不超过3000个。
• 订阅有效期为60 - 2592000秒（即60秒到30天），过期后需要重新订阅。如果未过期的情况下重复订阅，新设置的有效期会覆盖之前的有效期。
• 在线状态事件会受推送的影响：如果应用被清理，但厂商推送（APNS、小米、华为、OPPO、VIVO、魅族、FCM）可达，则默认不会触发该用户断开连接的事件,若开发者需要该种情况下视为离线，请前往网易云信控制台>选择应用>IM专业版>功能配置>在线状态配置自行修改；如果没有集成推送，或者推送不可达，则当用户断开连接时，会触发断开连接事件。
• 系统默认的在线状态事件值(value)为：1 - 登录，2 - 登出，3 - 断开连接。若需要设置自定义状态，如忙碌等，请自行发布事件。
• 订阅者登录的时候，如果被订阅者是在线的，那么会收到其在线的事件回调；但是如果对方是离线的，那么订阅者无法收到其离线的事件回调(如果后续对方重新登录，才能触发在线状态事件)。建议登录时将所有账号的在线状态设置为离线，这样设置，登录时无论对方是在线，还是从离线变更为在线，都能正常触发回调。
• IM的好友关系和在线状态是两个不同的功能，只添加好友是不会显示对方的在线状态的。
• 在线状态事件订阅是单向的，双方需要各自订阅。

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