从 6.3 版本开始,IMSDK 提供了用户状态管理的功能,每个用户拥有两种不同类型的状态:
说明:用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询或者按设备设置状态。
用户的普通状态类型有以下三种:
logout
(Android / iOS & Mac / Windows) 退出登录,但长连接中断的状态。通常情况下,此时可以接收到离线推送的消息。logout
退出登录。关于离线状态,需要注意的是:
注意:
- 下文所述的部分功能仅旗舰版客户支持,使用前请确认。
- 下文所述的部分功能需要在 即时通信 IM 控制台 打开对应的用户状态开关,使用前请确认。
您可以调用接口 setSelfStatus
(Android / iOS & Mac / Windows) 设置 customStatus
字段来设置自己的自定义状态。
如果您提前调用 addIMSDKListener
(Android / iOS & Mac) 添加了 SDK 监听器,设置成功后会触发 onUserStatusChanged
(Android / iOS & Mac / Windows) 回调。详情请参见下文的 状态变更通知。
自定义状态清除机制:
setSelfStatus
接口时,通过将 customStatus
字段设置为空来主动清除。说明:
- 调用
setSelfStatus
不需要升级到旗舰版,也无需开启控制台开关。- 本接口不做限频控制。
接口原型:
/**
* 5.4 设置自己的状态,从 6.3 版本开始支持
*
* @param status 待设置的自定义状态
*
* @note 请注意,该接口只支持设置自己的自定义状态,即 V2TIMUserStatus.customStatus
*/
public abstract void setSelfStatus(V2TIMUserStatus status, V2TIMCallback callback);
V2TIMUserStatus
参数解释:
字段 | 含义 | 是否必填 | 备注 |
---|---|---|---|
userID | 用户 ID | 否 | 只读,不可设置 |
statusType | 普通状态 | 否 | 只读,不可设置 |
customStatus | 自定义状态 | 否 | 当该字段为空时,清除自定义状态 |
示例代码如下所示:
V2TIMUserStatus status = new V2TIMUserStatus();
boolean clearStatus = true;
if (clearStatus) {
status.setCustomStatus(null);
} else {
status.setCustomStatus("listening music");
}
V2TIMManager.getInstance().setSelfStatus(status, new V2TIMCallback() {
@Override
public void onSuccess() {
Log.i(TAG, "setSelfStatus success, CustomStatus is " + customStr);
}
@Override
public void onError(int code, String desc) {
Log.e(TAG, "setSelfStatus error code = " + code + ",des = " + desc);
}
});
您可以调用 getUserStatus
(Android / iOS & Mac / Windows) 接口查询自己和其他用户的状态,接口会返回被查询者的普通状态和自定义状态。
接口原型:
/**
* 5.3 查询用户状态,从 6.3 版本开始支持
*
* @param userIDList 需要获取的用户 ID
*
* @note 请注意:
* - 如果您想查询自己的自定义状态,您只需要传入自己的 userID 即可
* - 当您批量查询时,接口只会返回查询成功的用户状态信息;当所有用户均查询失败时,接口会报错
*/
public abstract void getUserStatus(List<String> userIDList, V2TIMValueCallback<List<V2TIMUserStatus>> callback);
参数解释:
字段 | 含义 | 是否必填 | 备注 |
---|---|---|---|
userIDList | 待查询的用户 ID 列表 | 是 | 查询自己时,只需要传入自己的 ID 即可 |
设置 userIDList
仅包含自己的 userID,可查询自己的状态。
说明:
- 查询自己的状态不需要升级到旗舰版,也无需开启控制台开关。
- 查询自己的状态不做接口限频控制。
示例代码:
String myId = V2TIMManager.getInstance().getLoginUser();
if (myId == null || myId.isEmpty()) {
// login first
return;
}
List<String> ids = Arrays.asList(myId);
V2TIMManager.getInstance().getUserStatus(ids, new V2TIMValueCallback<List<V2TIMUserStatus>>() {
@Override
public void onSuccess(List<V2TIMUserStatus> v2TIMUserStatuses) {
// 查询自己的状态成功
}
@Override
public void onError(int code, String desc) {
// 查询自己的状态失败
}
});
设置 userIDList
为其他人的 userID 列表,可查询其他人的状态。
查询其他用户状态需要升级到旗舰版,详情请参见 基础服务详情。
查询其他用户状态需要提前在 即时通信 IM 控制台 开启 ”用户状态查询及状态变更通知“。如果开关关闭,调用 getUserStatus
会报错。
说明:接口限频默认为 5 秒 20 次请求,单次查询最大用户数不超过 500 人。
示例代码:
List<String> ids = Arrays.asList("userid1", "userid2", "userid3");
V2TIMManager.getInstance().getUserStatus(ids, new V2TIMValueCallback<List<V2TIMUserStatus>>() {
@Override
public void onSuccess(List<V2TIMUserStatus> v2TIMUserStatuses) {
// 查询状态成功
}
@Override
public void onError(int code, String desc) {
// 查询状态失败
}
});
您可以调用接口 subscribeUserStatus
(Android / iOS & Mac / Windows)订阅指定用户的状态。IM SDK 默认只支持订阅 200 个用户,当超过限制后,会淘汰掉最早订阅的用户。
当您所订阅的用户状态变更时(包括普通状态和自定义状态),您可以在 onUserStatusChanged
(Android / iOS & Mac / Windows) 回调中收到该用户的状态变更通知。
接口特性:
该接口不支持订阅自己的状态。如果您想感知自己的状态变更,可直接监听 onUserStatusChanged
回调。详情请参见下文的 状态变更通知。
该接口支持订阅好友的状态,但是订阅好友也会占用上述 200 个用户的名额。
如果您关心所有好友的状态,不需要调用本接口,直接在 即时通信 IM 控制台 开启好友状态自动通知开关,开启后可以在 onUserStatusChanged
回调中收到所有好友的状态变更通知。
如果您仅关心部分好友的状态,只能调用 subscribeUserStatus
主动订阅。订阅后可以在 onUserStatusChanged
回调中所订阅的好友的状态变更通知。
订阅用户状态需要升级到旗舰版,详情请参见 基础服务详情。
订阅用户状态需要提前在 即时通信 IM 控制台 开启 ”用户状态查询及状态变更通知“。如果开关关闭,调用 subscribeUserStatus
会报错。
说明:接口限频默认为 5 秒 20 次请求,单次订阅最大用户数不超过 100 人。
接口原型:
/**
* 5.5 订阅用户状态,从 6.3 版本开始支持
*
* @param userIDList 待订阅的用户 ID
*
* @note 请注意
* - 当成功订阅用户状态后,当对方的状态(包含在线状态、自定义状态)发生变更后,您可以监听 @onUserStatusChanged 回调来感知
* - 如果您需要订阅好友列表的状态,您只需要在控制台上打开开关即可,无需调用该接口
* - 该接口不支持订阅自己,您可以通过监听 @onUserStatusChanged 回调来感知自身的自定义状态的变更
* - 订阅列表有个数限制,超过限制后,会自动淘汰最先订阅的用户
*/
public abstract void subscribeUserStatus(List<String> userIDList, V2TIMCallback callback);
示例代码如下所示:
List<String> useridList = Arrays.asList("userid1", "userid2", "userid3");
V2TIMManager.getInstance().subscribeUserStatus(useridList, new V2TIMCallback() {
@Override
public void onSuccess() {
// 订阅状态成功
}
@Override
public void onError(int code, String desc) {
// 订阅状态失败
}
});
如果您不想接收用户的状态变更通知,您可以调用接口 unsubscribeUserStatus
(Android / iOS & Mac / Windows) 取消订阅用户的状态或清空订阅列表。
如果您不想主动清空订阅列表,当帐号离线或者退出登录后,IMSDK 默认延迟一段时间后自动清空订阅列表。
取消订阅用户状态需要升级到旗舰版,详情请参见 基础服务详情。
取消订阅用户状态需要提前在 即时通信 IM 控制台 开启 ”用户状态查询及状态变更通知“。如果开关关闭,调用 unsubscribeUserStatus
会报错。
说明:接口限频默认为 5 秒 20 次请求,单次取消订阅最大用户数不超过 100 人。
接口原型:
/**
* 5.6 取消订阅用户状态,从 6.3 版本开始支持
*
* @note
* - 当 userIDList 为空或者 nil 时,取消当前所有的订阅
*/
public abstract void unsubscribeUserStatus(List<String> userIDList, V2TIMCallback callback);
示例代码如下所示:
List<String> useridList = Arrays.asList("userid1", "userid2", "userid3");
V2TIMManager.getInstance().unsubscribeUserStatus(useridList, new V2TIMCallback() {
@Override
public void onSuccess() {
// 取消订阅状态成功
}
@Override
public void onError(int code, String desc) {
// 取消订阅状态失败
}
});
根据您希望感知用户状态的用户类型,可以将状态变更分为 3 种类型:
上述 3 种方式的状态变更通知,都是通过 onUserStatusChanged
(Android / iOS & Mac / Windows) 回调出来。
回调原型:
/**
* 用户状态变更通知
*
* @note 收到通知的情况:
* 1. 订阅过的用户发生了状态变更(包括在线状态和自定义状态),会触发该回调
* 2. 在 IM 控制台打开了好友状态通知开关,即使未主动订阅,当好友状态发生变更时,也会触发该回调
* 3. 同一个账号多设备登录,当其中一台设备修改了自定义状态,所有设备都会收到该回调
*/
public void onUserStatusChanged(List<V2TIMUserStatus> userStatusList){}
虽然状态通知都通过 onUserStatusChanged
抛出,但不同类型的用户触发该通知的方式不同。
如果您提前调用 addIMSDKListener
添加了 SDK 监听器,设置成功后会,当自己的状态发生变更时,会触发 onUserStatusChanged
回调,您可以在其中获取到自己的最新状态。
如果您在 即时通信 IM 控制台 开启了好友状态自动通知,那么当好友的状态发生变更时,会自动触发 onUserStatusChanged
回调,您可以在其中获取到好友的最新状态。
如果您没有开启好友状态自动通知,并且仍然想感知好友的状态变更,您需要调用 subscribeUserStatus
主动订阅好友的状态。当好友的状态发生变更时,会自动触发 onUserStatusChanged
回调。
注意:
subscribeUserStatus
仅旗舰版客户支持,并且需要开启控制台开关。详情请参见上文的 订阅用户状态。
subscribeUserStatus
主动订阅好友状态,那么当好友状态发生变更时,您将无法感知到。如果您希望感知普通用户(非好友)的状态变更,只能调用 subscribeUserStatus
主动订阅。当该用户状态发生变更时,会触发 onUserStatusChanged
回调,您可以在其中获取到其最新状态。
注意:
subscribeUserStatus
仅旗舰版客户支持,并且需要开启控制台开关。详情请参见上文的 订阅用户状态。
示例代码如下:
private void initListener() {
V2TIMSDKListener v2TIMSDKListener = new V2TIMSDKListener() {
@Override
public void onUserStatusChanged(List<V2TIMUserStatus> userStatusList) {
String myID = V2TIMManager.getInstance().getLoginUser();
for (V2TIMUserStatus item : userStatusList) {
if (item.getUserID().equals(myID)) {
// 自己的状态发生变更
} else {
// 其他人的状态发生变更
}
}
}
};
V2TIMManager.getInstance().addIMSDKListener(v2TIMSDKListener);
}
说明:除了上述通过
onUserStatusChanged
得知用户状态以外,您还可以主动查询用户状态,详情请参见上文 查询用户状态。
如果您开启了多端登录(详情请参见 多端登录),同一个帐号可以在不同设备上登录。当其中一个设备上所登录的用户的状态发生变更时,后台会给其他登录的设备也下发 onUserStatusChanged
(Android / iOS & Mac / Windows) 通知。
setSelfStatus
接口不限制旗舰版。getUserStatus
查询自己的状态,不限制旗舰版。getUserStatus
除了查询自己外的其他能力,均需要升级到旗舰版。subscribe
/ unsubscribe
接口的所有能力,均需要升级到旗舰版setSelfStatus
接口不限频。getUserStatus
查询自己的状态,不限频。getUserStatus
除了查询自己的状态外,默认限制 5 秒 20 次请求,单次查询最大用户数不超过 500。subscribe
接口,默认限制 5 秒 20 次请求,单次订阅最大用户数不超过 100。unsubscribe
接口,默认限制 5 秒 20 次请求,单次取消订阅最大用户数不超过 100。72001 错误码表示在控制台上并没有开启对应的能力,请登录 即时通信 IM 控制台 打开对应的功能开关。
本页内容是否解决了您的问题?