iOS

在线状态订阅

更新时间: 2024/07/09 16:04:30

功能概述

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

目前,仅开放类型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 订阅请求对象。

在订阅事件中,订阅请求中必需填写 typeexpirypublishers 字段。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 , valuetype 目前仅支持 “在线状态事件” , 即 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 即时通讯下的功能配置按钮进入功能配置页。

    image.png
  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 实现。

此文档是否对你有帮助?
有帮助
去反馈
  • 功能概述
  • 前提条件
  • 订阅事件
  • 取消订阅
  • 发布自定义事件
  • 监听所订阅的事件
  • 查询订阅事件关系
  • 在线状态事件