在线状态订阅

功能概述

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

订阅事件

• API 介绍

向特定用户订阅特定事件。无论是内置的在线状态事件或是自定义的事件，都需要通过该接口发起订阅。每个帐号最大有效订阅帐号不超过 3000 个。 对于订阅有效期，由于多端订阅（指同一账号在其他类型客户端订阅）会覆盖这个时长，所以建议开发者各端订阅时长保持一致。此外，需要注意的是，为了性能考虑，在30秒内对同一账号同一事件订阅，即使设置为立即同步服务的也不会下发目标事件。

• API 原型

dart
/// 订阅事件
/// [request] 订阅请求信息 必须填写事件类型、事件发布者账号以及订阅有效期

 Future<NIMResult<List<String>>> registerEventSubscribe(
      EventSubscribeRequest request) async

• 参数说明

EventSubscribeRequest 属性说明

参数	类型	说明
eventType	int	事件类型，仅支持传入1
expiry	int	订阅的有效期，范围为 60s 到 30 days，数值单位为秒
syncCurrentValue	bool	订阅后是否立刻同步事件状态值，默认为 false
publishers	List<String>	事件发布者的账号集合

在订阅事件中，订阅请求中必需填写 eventType，expiry，publishers 字段。

• 示例

dart final result = await NimCore.instance.eventSubscribeService
            .registerEventSubscribe(eventSubscribeRequest);

取消订阅

按账号取消订阅

• API 介绍

可以取消订阅指定账号的指定类型的事件，订阅请求中必须填写 eventType、 publishers 字段。

• API 原型

dart
 /// 按账号取消指定事件的订阅关系
 /// [request] 取消订阅信息，只需填写事件类型和事件发布者账号集合（被订阅者集合）
 
 Future<NIMResult<bool>> unregisterEventSubscribe(
      EventSubscribeRequest eventSubscribeRequest)

• 示例

dart final result = await NimCore.instance.eventSubscribeService
            .unregisterEventSubscribe(eventSubscribeRequest);

按事件取消订阅

取消指定事件的全部订阅关系。

• API 原型

dart
 /// 取消指定事件的全部订阅关系
 /// [request] 取消订阅信息，只需填写事件类型。
 
Future<NIMResult<bool>> batchUnSubscribeEvent( EventSubscribeRequest request);

• 示例

dart final result = await NimCore.instance.eventSubscribeService
            .batchUnSubscribeEvent(eventSubscribeRequest);

发布事件

• API 介绍

向订阅者发布事件。若云信系统内置的在线状态无法满足应用需求或者开发者需要一些单独的自定义事件时，可以使用该接口来发布。

• API 原型

dart
 /// 发布事件
 /// [event] 事件
 
Future<NIMResult<bool>> publishEvent(Event event);

发布事件时，需要自行构造出 Event 对象，必须需要填写的字段为：

• eventType：传1即可。
• eventValue：value为10000以上(1-9999为云信预定义值，开发者不可使用)。

Event 接口说明：

类型	Event 字段	说明
eventType	int	设置事件类型，发布事件时可用
eventValue	int	设置事件值，发布事件时可用
config	String	设置事件的扩展字段，由客户端发布事件时配置
broadcastOnlineOnly	bool	事件发布后，是否只广播给在线的订阅者
expiry	int	设置事件有效期，单位秒，范围为 60s 到 7days
isBroadcastOnlineOnly	bool	事件是否只广播给在线的订阅者
publisherAccount	String	事件发布者
publisherClientType	int	事件发布客户端类型，参考ClientType
publishTime	int	事件发布时间
multiClientConfigMap	Map<int, String>	某种类型客户端发布的事件扩展信息
String	nimConfig	预留事件中的配置信息，由服务端填入

示例

dartawait NimCore.instance.eventSubscribeService.publishEvent(event);

监听所订阅的事件

• API 介绍

通过 StreamController<List<Event>> eventSubscribeStream监听所订阅的事件。

• API 原型

dart
 /// 监听事件状态变更
 /// [observer] 观察者，参数为最新的事件状态信息
 /// [register] true为注册监听，false为取消监听
 
  final StreamController<List<Event>> eventSubscribeStream =
      StreamController<List<Event>>.broadcast();

• 示例

dartNimCore.instance.eventSubscribeService.eventSubscribeStream.listen((List<Event> eventList) {

        });

查询事件订阅

• API 介绍

支持查询事件订阅，用于查询某种事件的订阅关系。

• API 原型

dart
 /// 查询指定事件类型的订阅关系
 /// [request] 查询订阅信息，必须填写事件类型、事件发布者账号,填写后将查询指定发布者的订阅关系。 
Future<NIMResult<List<EventSubscribeResult>>> querySubscribeEvent(
      EventSubscribeRequest request)

• 参数说明

EventSubscribeResult 说明

参数	类型	说明
eventType	int	事件类型，传1即可
expiry	int	订阅的有效期，范围为 60s 到 30days，数值单位为秒
time	int	事件订阅的时间
publisherAccount	List<String>	事件发布者账号集合

• 示例

dartfinal result = await NimCore.instance.eventSubscribeService
            .querySubscribeEvent(request);

在线状态事件

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

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

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也在线，则依旧可以监听到。