事件订阅(在线状态)

事件订阅和事件发布功能,事件均为 Event 对象,事件有两个重要的属性:事件类型 type 和事件值 value,一种 type 的事件会存在多个 value,比如在线状态事件,它的type = 1,登入和登出则是两个不同 value 的事件。在服务器允许的情况下, 任何人都可以发布 Event,订阅者则能够收到该 Event。事件不保存,同一账号的同一类型事件,后发布将会覆盖之前发布。当有新事件产生时(服务端产生或者客户端发布),服务端会对所有订阅者下发该事件。

事件类型 1-99999 为网易云通信预留,目前仅使用事件类型 1 为在线状态事件 NimOnlineStateEvent,预留事件比普通事件多一个 nimConfig 字段信息,该字段为服务端填写,对于在线状态事件,nimConfig 字段值为一段 json ,携带各端是否在线的信息。

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() 获取预留事件中的配置信息,由服务端填入

订阅事件

用于订阅指定账号的指定类型的事件,需要指定事件类型、事件发布者集合、订阅有效期,以及是否立即同步事件。订阅有效期范围为 60 秒到 30 天,数值单位为秒,是否立即同步事件若设置为true则订阅成功后会立即返回目标事件。

对于订阅有效期,由于多端订阅会覆盖这个时长,所以建议开发者各端订阅时长保持一致。此外,需要注意的是,为了性能考虑,在30秒内对同一账号同一事件订阅,即使设置为立即同步服务的将不会下发目标事件。

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

EventSubscribeRequest 属性说明

参数 说明
eventType 事件类型,1-99999 为云信保留类型
expiry 订阅的有效期,范围为 60s 到 30days,数值单位为秒
syncCurrentValue 订阅后是否立刻同步事件状态值,默认为 false
publishers 事件发布者的账号集合

在订阅事件中,订阅请求中必需填写 eventTypeexpirypublishers 字段。

NIMClient.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 {

        }
    }
});

取消订阅事件

可以取消订阅指定账号的指定类型的事件,指定取消订阅的事件类型以及事件发布者集合。

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

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

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

发布事件

目前网易云通信支持客户端发布类型 1 并且值为 10001 的事件,仅用于设置事件的多端配置信息,多端同时在线时设置了该信息后服务端会将这些设置合并后下发,订阅者收到事件之后可以通过 Event#getConfigByClient 方法获取该账号的多端信息。

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

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

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

查询事件订阅

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

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

EventSubscribeResult 说明

参数 说明
eventType 事件类型,1-99999 为云信保留类型
expiry 订阅的有效期,范围为 60s 到 30days,数值单位为秒
time 事件订阅的时间
publisherAccount 事件发布者账号集合
NIMClient.getService(EventSubscribeService.class).querySubscribeEvent(request);

监听事件

通过 EventSubscribeServiceObserver监听接口监听接收到的事件,开发者必须将此监听生命周期与 Application 生命周期一致。

/**
 * 监听事件状态变更
 *
 * @param observer 观察者,参数为最新的事件状态信息
 * @param register true为注册监听,false为取消监听
 */
void observeEventChanged(Observer<List<Event>> observer, boolean register);
NIMClient.getService(EventSubscribeServiceObserver.class).observeEventChanged(new Observer<List<Event>>() {
    @Override
    public void onEvent(List<Event> events) {
        // 处理
    }
}, true);