功能概述

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

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

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

前提条件

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

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

使用限制

• 每次调用最多只能订阅 100 个账号，数量较多需多次调用。
• 在线状态事件订阅，每个用户账号最大有效订阅账号数不超过 3000 个。超过 3000 则默认删除最老的订阅。

订阅事件

• API 介绍

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

• API 原型

java/**
* 订阅事件
*
* @param request 订阅请求信息 必须填写事件类型、事件发布者账号以及订阅有效期
* @return InvocationFuture 可以设置回调函数。请求完成后才会调用，返回订阅失败的账号集合，如果数组长度为0则全部成功。如果出错，会有具体的错误代码。
*/
InvocationFuture<List<String>> subscribeEvent(EventSubscribeRequest request);

• 参数说明

EventSubscribeRequest 属性说明

参数	说明
eventType	事件类型，仅支持传入1
expiry	订阅的有效期，60 - 2592000，单位：秒，过期后需要重新订阅。如果未过期的情况下重复订阅，新设置的有效期会覆盖之前的有效期。
syncCurrentValue	订阅后是否立刻同步事件状态值，默认为 false
publishers	事件发布者的账号集合

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

• 示例

javaNIMClient.getService(EventSubscribeService.class).subscribeEvent(eventSubscribeRequest).setCallback(new RequestCallbackWrapper<List<String>>() {
    @Override
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            if (result != null) {
                // 部分订阅失败的账号。。。
                //
                //
            }
        } else {

        }
    }
});

取消订阅

按账号取消订阅

• API 介绍

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

• API 原型

java/**
 * 按账号取消指定事件的订阅关系
 *
 * @param request 取消订阅信息，只需填写事件类型和事件发布者账号集合（被订阅者集合）
 * @return InvocationFuture 可以设置回调函数。请求完成后才会调用，返回取消订阅失败的账号集合，如果数组长度为0则全部成功。如果出错，会有具体的错误代码。
 */
InvocationFuture<List<String>> unSubscribeEvent(EventSubscribeRequest request);

• 示例

javaNIMClient.getService(EventSubscribeService.class).unSubscribeEvent(eventSubscribeRequest);

按事件取消订阅

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

• API 原型

java/**
 * 取消指定事件的全部订阅关系
 *
 * @param request 取消订阅信息，只需填写事件类型。
 * @return InvocationFuture 可以设置回调函数。请求完成后才会调用。如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> batchUnSubscribeEvent(EventSubscribeRequest request);

• 示例

javaNIMClient.getService(EventSubscribeService.class).batchUnSubscribeEvent(request);

发布自定义事件

• API 介绍

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

• API 原型

java/**
 * 发布自定义事件
 *
 * @param event 事件
 * @return InvocationFuture 可以设置回调函数。请求完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Event> publishEvent(Event event);

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

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

Event 接口说明：

返回值	Event 接口	说明
void	setEventType(int eventType)	设置事件类型，发布自定义事件时可用
void	setEventValue(int eventValue)	设置事件值，发布自定义事件时可用
void	setConfig(String config)	设置事件的扩展字段，由客户端发布自定义事件时配置
void	setBroadcastOnlineOnly(boolean only)	事件发布后，是否只广播给在线的订阅者
void	setExpiry(long expiry)	设置事件有效期，单位秒，范围为 60s 到 7days
void	setSyncSelfEnable(boolean syncSelfEnable)	设置事件是否支持多端同步
int	getEventType()	获取事件类型
int	getEventValue()	获取事件值
String	getConfig()	获取事件扩展字段
long	getExpiry()	获取事件有效期
boolean	isBroadcastOnlineOnly()	事件是否只广播给在线的订阅者
String	getPublisherAccount()	获取事件发布者
int	getPublisherClientType()	获取事件发布客户端类型，具体类型见ClientType
long	getPublishTime()	获取事件发布时间
String	getConfigByClient(int client)	获取某种类型客户端发布的事件扩展信息
String	getNimConfig()	获取预留事件中的配置信息，由服务端填入

示例

javaNIMClient.getService(EventSubscribeService.class).publishEvent(event);

监听所订阅的事件

• API 介绍

通过 EventSubscribeServiceObserver监听接口监听所订阅的事件，开发者必须将此监听生命周期保持与 Application 生命周期一致。

• API 原型

java/**
 * 监听事件状态变更
 *
 * @param observer 观察者，参数为最新的事件状态信息
 * @param register true为注册监听，false为取消监听
 */
void observeEventChanged(Observer<List<Event>> observer, boolean register);

• 示例

javaNIMClient.getService(EventSubscribeServiceObserver.class).observeEventChanged(new Observer<List<Event>>() {
    @Override
    public void onEvent(List<Event> events) {
        // 处理
    }
}, true);

查询事件订阅

• API 介绍

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

• API 原型

java/**
 * 查询指定事件类型的订阅关系
 * @param request 查询订阅信息，必须填写事件类型、事件发布者账号,填写后将查询指定发布者的订阅关系。
 * @return InvocationFuture 可以设置回调函数。请求完成后才会调用。如果出错，会有具体的错误代码。
 */
InvocationFuture<List<EventSubscribeResult>> querySubscribeEvent(EventSubscribeRequest request);

• 参数说明

EventSubscribeResult 说明

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

• 示例

javaNIMClient.getService(EventSubscribeService.class).querySubscribeEvent(request);

在线状态事件

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

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

1. 在控制台首页应用管理中选择应用，然后单击 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也在线，则依旧可以监听到。