事件订阅(在线状态)

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

订阅事件

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

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

EventSubscribeRequest 属性说明

参数 说明
eventType 事件类型,仅支持传入1
expiry 订阅的有效期,范围为 60s 到 30 days,数值单位为秒
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 {

        }
    }
});

取消订阅

按账号取消订阅

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

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

按事件取消订阅

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

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

发布事件

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

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

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

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

示例

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

监听所订阅的事件

通过 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);

查询事件订阅

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

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

EventSubscribeResult 说明

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

在线状态事件

在线状态(在线、异常断开、登出)为云信系统内置事件,只需向销售发起申请,申请成功后,即可使用。无需主动发布事件状态。典型的应用场景为A订阅了B的在线状态事件,则当A登录成功后,可以即时获取B此时的在线状态:在线、异常断开或是登出状态。

注意事项:

如前所述,在线状态事件为云信系统内置事件,无需开发者主动发布。在A订阅了B的type=1事件后,当A登录时,若B此时在线,则会收到对应的事件;若后续B再登录上线时,且A也在线,则依旧可以监听到。