Presence

Presence 提供监控用户上线、下线及用户历史状态变更通知的能力。通过 Presence 功能，你可以实时获取以下信息：

• 用户加入或离开指定频道的实时事件通知
• 自定义临时用户状态及其变更实时事件通知
• 查询指定用户加入或订阅了哪些频道
• 查询指定频道有哪些用户加入及其用户临时状态数据

信息

Presence 能力适用于 Message Channel 和 Stream Channel。

RtmPresence

whoNow

接口描述

调用 whoNow 方法，你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。

接口方法

你可以通过以下方式调用 whoNow 方法：

Java

void whoNow(
    String channelName,
    RtmChannelType channelType,
    PresenceOptions options,
    ResultCallback<WhoNowResult> resultCallback
);

参数	类型	是否必填	默认值	描述
channelName	string	必填	-	频道名称。
channelType	RtmChannelType	必填	-	频道类型。详见 RtmChannelType。
options	PresenceOptions	必填	-	查询附加选项。
resultCallback	ResultCallback<WhoNowResult>	必填	-	调用结果回调： 调用成功：执行 onSuccess 方法并返回 WhoNowResult 查询结果。 调用失败：执行 onFailure 方法，返回错误结果。

options 参数包含以下属性：

属性	类型	是否必填	默认值	描述
includeUserId	boolean	选填	true	返回结果中是否包含在线成员的用户 ID。
includeState	boolean	选填	false	返回结果中是否包含在线用户的临时状态数据。
page	String	选填	-	页码书签。如果不填写，则 SDK 默认返回第一页结果。你可以在返回值中查看是否还有下一页。

WhoNowResult 数据包含以下属性：

属性	类型	描述
NextPage	String	下一页书签。通过该属性可以确认是否有下一页： 值为空表示没有下一页。 值不为空表示有下一页。你可以将该值填写在 whoNow 的 page 属性中，从而查询下一页结果。
UserStateList	ArrayList<UserState>	频道在线用户及其临时状态信息列表。
totalOccupancy	long	UserStateList 列表长度，当 whoNow 属性中 includeUserId、includeState 属性都设置为 false 时，此值表示频道当前总在线人数。

UserState 数据类型包含如下属性：

属性	类型	描述
userId	String	用户 ID。
states	HashMap<String, String>	用户临时状态数组。

基本用法

Java

PresenceOptions options = new PresenceOptions();
options.setIncludeUserId(true);
options.setIncludeState(true);
options.setPage("yourBookMark");

rtmClient.getPresence().whoNow("channelName", RtmChannelType.MESSAGE, options, new ResultCallback<WhoNowResult>() {
    @Override
    public void onSuccess(WhoNowResult result) {
        log(CALLBACK, "whoNow success");
        for (UserState state : result.getUserStateList()) {
            log(INFO, "user id: " + state.getUserId());
            state.getStates().forEach((key, value) -> {
                log(INFO, "key: " + key + ", value: " + value);
            });
        }
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

whereNow

接口描述

在数据统计、App 调试等场景中，你可能需要了解指定用户订阅或加入的所有频道。调用 whereNow 方法，你可以实时获取指定用户所在频道的列表。

接口方法

你可以通过以下方式调用 whereNow 方法：

Java

void whereNow(
    String userId,
    ResultCallback<ArrayList<ChannelInfo>> resultCallback
);

参数	类型	是否必填	默认值	描述
userId	string	必填	-	用户 ID。
resultCallback	ResultCallback<ArrayList<ChannelInfo>>	必填	-	调用结果回调： 调用成功：执行 onSuccess 方法并返回 ArrayList<ChannelInfo> 查询结果。 调用失败：执行 onFailure 方法。

ChannelInfo数据类型包含以下属性：

属性	类型	描述
channelName	String	频道名称。
channelType	RtmChannelType	频道类型。详见 RtmChannelType。

基本用法

Java

rtmClient.getPresence().whereNow("Tony", new ResultCallback<ArrayList<ChannelInfo>>() {
    @Override
    public void onSuccess(ArrayList<ChannelInfo> channels) {
        log(CALLBACK, "get " + queryUserId + " whereNow success");
        for (ChannelInfo channel : channels) {
            log(INFO, channel.toString());
        }
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

setState

接口描述

为满足不同业务场景对用户状态的设置需求，RTM 提供 setState 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。

设置成功后，只要用户保持订阅频道并一直在线，自定义状态就会在频道中持续存在。setState 方法设置的是临时用户状态，当用户离开频道或断开与 RTM 的连接时，状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态，你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据，声网推荐改用 Storage 功能的 setUserMetadata 方法。

如果用户修改了临时用户状态，RTM 会实时触发 REMOTE_STATE_CHANGED 类型的 onPresenceEvent 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。

接口方法

你可以通过以下方式调用 setState 方法：

Java

void setState(
    String channelName,
    RtmChannelType channelType,
    Map<String, String> items,
    ResultCallback<Void> resultCallback
);

参数	类型	是否必填	默认值	描述
channelName	String	必填	-	频道名称
channelType	RtmChannelType	必填	-	频道类型。详见 RtmChannelType。
items	Map<String, String>	必填	-	用户状态键值对。
resultCallback	ResultCallback<Void>	必填	-	调用结果回调： 调用成功：执行 onSuccess 方法。 调用失败：执行 onFailure 方法。

基本用法

Java

HashMap<String, String> stateItems = new HashMap<String, String>();
stateItems.put("mood", "pumped");

rtmClient.getPresence().setState("channelName", RtmChannelType.MESSAGE, stateItems, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        log(CALLBACK, "set state success");
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

getState

接口描述

如需获取指定频道中指定用户的临时用户状态，你可以调用 getState 方法。

接口方法

你可以通过以下方式调用 getState 方法：

Java

void getState(
    String channelName,
    RtmChannelType channelType,
    String userId,
    ResultCallback<UserState> resultCallback
)

参数	类型	是否必填	默认值	描述
channelName	String	必填	-	频道名称。
channelType	RtmChannelType	必填	-	频道类型。详见 RtmChannelType。
userId	String	必填	-	用户 ID。
resultCallback	ResultCallback<UserState>	必填	-	调用结果回调： 调用成功：执行 onSuccess 方法并返回 UserState 查询结果。 调用失败：执行 onFailure 方法。

UserState 数据类型包含如下属性：

属性	类型	描述
userId	String	用户 ID。
states	HashMap<String, String>	用户临时状态数组。

基本用法

Java

rtmClient.getPresence().getState("channelName", RtmChannelType.MESSAGE, "Tony", new ResultCallback<UserState>() {
    @Override
    public void onSuccess(UserState state) {
        log(CALLBACK, "get users(" + state.getUserId() + ") state success");
        state.getStates().forEach((key, value) -> {
            log(INFO, "key: " + key + ", value: " + value);
        });
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

removeState

接口描述

当不再需要某个临时用户状态时，你可以调用 removeState 方法删除自己的一个或多个临时状态。成功删除用户状态后，订阅该频道且开启 Presence 事件监听的用户会收到 REMOTE_STATE_CHANGED 类型的 onPresenceEvent 事件通知，详见事件监听。

接口方法

你可以通过以下方式调用 removeState 方法：

Java

void removeState(
    String channelName,
    RtmChannelType channelType,
    ArrayList<String> keys,
    ResultCallback<Void> resultCallback
);

参数	类型	是否必填	默认值	描述
channelName	String	必填	-	频道名称
channelType	RtmChannelType	必填	-	频道类型。详见 RtmChannelType。
keys	ArrayList<String>	必填	-	需要删除状态的 key 列表。如果不填写，则删除全部状态。
resultCallback	ResultCallback<Void>	必填	-	调用结果回调： 调用成功：执行 onSuccess 方法。 调用失败：执行 onFailure 方法。

基本用法

Java

ArrayList<String> keys = new ArrayList<>(Arrays.asList("A", "B", "C"));
rtmClient.getPresence().removeState("channelName", RtmChannelType.MESSAGE, keys, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        log(CALLBACK, "remove state success");
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});