功能描述
从 6.3 版本开始,SDK 提供了用户状态管理的功能,每个用户拥有两种不同类型的状态:
普通状态。SDK 内置状态,客户无法直接修改。
自定义状态。客户自定义的状态,可以自行修改。利用自定义状态,您可以对该账号设置诸如“听歌中”、“通话中”等一些自定义信息。
用户的普通状态有以下 3 种:
在线(ONLINE):当前用户已登录上线,可以正常收发消息。
未登录(UNLOGINED):用户注册账号后从未登录过,或者用户主动调用 logout
退出登录。
关于离线状态,需要注意的是:
1. App 登录过程中结束进程或者网络异常中断(例如 4G/Wifi 切换、电梯信号弱等),此时账号会处于离线状态。
2. App 登录后按 Home 键进入后台,如果 App 进程被系统 kill,此时账号会处于离线状态。如果 App 进程处于后台保活,此时账号仍然是在线状态。
3. 在线/离线的状态切换,依赖于 SDK 与后台服务之间的 TCP 长连接。当客户端处于飞行模式、网络彻底中断或者某些设备厂商不支持时,可能会出现 TCP 协议的 FIN 包或 RST 包无法发出的现象,从而导致无法立即切换成离线状态。但由于后台服务接收不到心跳包,400 秒后依然会将当前用户状态设置为离线状态。
注意:
1. 用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询、设置状态。
3. 下文所述的部分功能需要在控制台打开 Set user status query and status change notification
开关,开关路径:Applications > Your App > Chat > Configuration > Login and Message > Set user status query and status change notification。 效果展示
您可以使用本功能,在您的 App 中展示用户的在线状态及自定义状态,效果图如下所示:
设置自己的自定义状态
自定义状态清除机制:
1. 您可以在调用 setSelfStatus
接口时,设置 customStatus
为空来主动清除状态。
2. 当 SDK 监测到当前账号处于离线状态后,会自动清除自定义状态,此时也会触发状态变更通知。
说明
1. 调用 setSelfStatus
不需要升级到进阶版,也无需开启控制台开关。
2. customStatus
最大为 100 字节。
3. 本接口不做限频控制。
示例代码如下所示:
V2TIMUserStatus status = new V2TIMUserStatus();
boolean clearStatus = true;
if (clearStatus) {
status.setCustomStatus(null);
} else {
status.setCustomStatus("listening to music");
}
V2TIMManager.getInstance().setSelfStatus(status, new V2TIMCallback() {
@Override
public void onSuccess() {
Log.i(TAG, "setSelfStatus succeed, CustomStatus is " + status.getCustomStatus());
}
@Override
public void onError(int code, String desc) {
Log.e(TAG, "setSelfStatus error code = " + code + ", desc = " + desc);
}
});
V2TIMUserStatus *status = [[V2TIMUserStatus alloc] init];
BOOL clearStatus = YES;
if (clearStatus) {
status.customStatus = nil;
} else {
status.customStatus = @"listening to music";
}
[V2TIMManager.sharedInstance setSelfStatus:status
succ:^{
NSLog(@"setSelfStatus succeed, customStatus: %@", status.customStatus);
} fail:^(int code, NSString *desc) {
NSLog(@"setSelfStatus error, code: %d, desc: %@", code, desc);
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMUserStatus status;
bool clearStatus = true;
status.customStatus = clearStatus ? {} : "listening to music";
auto callback = new Callback{};
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->SetSelfStatus(status, callback);
查询用户状态
查询自己的状态
调用 getUserStatus
,设置 userIDList
仅包含自己的 userID,可查询自己的状态。
说明:
1. 查询自己的状态不需要升级到进阶版,也无需开启控制台开关。
2. 查询自己的状态不做接口限频控制。
示例代码:
String loginUserID = V2TIMManager.getInstance().getLoginUser();
if (loginUserID == null || loginUserID.isEmpty()) {
return;
}
List<String> ids = Arrays.asList(loginUserID);
V2TIMManager.getInstance().getUserStatus(ids, new V2TIMValueCallback<List<V2TIMUserStatus>>() {
@Override
public void onSuccess(List<V2TIMUserStatus> v2TIMUserStatuses) {
}
@Override
public void onError(int code, String desc) {
}
});
NSString *loginUserID = V2TIMManager.sharedInstance.getLoginUser;
if (loginUserID == nil || loginUserID.length == 0) {
return;
}
[V2TIMManager.sharedInstance getUserStatus:@[loginUserID]
succ:^(NSArray<V2TIMUserStatus *> *result) {
} fail:^(int code, NSString *desc) {
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T&)>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
ValueCallback() = default;
~ValueCallback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess(const T& value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMString loginUser = V2TIMManager::GetInstance()->GetLoginUser();
if (!loginUser.Empty()) {
V2TIMStringVector userIDList;
userIDList.PushBack(loginUser);
auto callback = new ValueCallback<V2TIMUserStatusVector>{};
callback->SetCallback(
[=](const V2TIMUserStatusVector& userStatusList) {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetUserStatus(userIDList, callback);
}
查询其他人的状态
设置 userIDList
为其他人的 userID 列表,可查询其他人的状态。
说明
2. 查询其他用户状态需要提前在控制台开启开关 Set user status query and status change notification
,开关路径:Applications > Your App > Chat > Configuration > Login and Message。如果开关关闭,调用 getUserStatus 会报错。 3. 接口限频默认为 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) {
}
});
[V2TIMManager.sharedInstance getUserStatus:@[@"userid1", @"userid2", @"userid3"]
succ:^(NSArray<V2TIMUserStatus *> *result) {
} fail:^(int code, NSString *desc) {
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T&)>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
ValueCallback() = default;
~ValueCallback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess(const T& value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMStringVector userIDList;
userIDList.PushBack(u8"userid1");
userIDList.PushBack(u8"userid2");
auto callback = new ValueCallback<V2TIMUserStatusVector>{};
callback->SetCallback(
[=](const V2TIMUserStatusVector& userStatusList) {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetUserStatus(userIDList, callback);
订阅用户状态
subscribeUserStatus
接口特性:
1. 该接口不支持订阅自己的状态。如果您想感知自己的状态变更,可直接监听 onUserStatusChanged
回调。详情请参见下文的 状态变更通知。 2. 该接口支持订阅好友的状态,订阅好友会占用上述 200 个用户的名额。
如果您关心所有好友的状态,不需要调用本接口,直接在控制台开启 Set user status query and status change notification
开关,开启后可以在 onUserStatusChanged
回调中收到所有好友的状态变更通知。 如果您仅关心部分好友的状态,只能调用 subscribeUserStatus
主动订阅。订阅后可以在 onUserStatusChanged
回调中所订阅的好友的状态变更通知。
说明
2. 订阅用户状态需要提前在控制台开启开关 Set user status query and status change notification
,开关路径:Applications > Your App > Chat > Configuration > Login and Message。如果开关关闭,调用 subscribeUserStatus 会报错。 3. 接口限频默认为 5 秒 20 次请求,单次订阅最大用户数不超过 100 人。
示例代码如下所示:
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) {
}
});
[V2TIMManager.sharedInstance subscribeUserStatus:@[@"userid1", @"userid2", @"userid3"] succ:^ {
} fail:^(int code, NSString *desc) {
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMStringVector userIDList;
userIDList.PushBack(u8"userid1");
userIDList.PushBack(u8"userid2");
auto callback = new Callback{};
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->SubscribeUserStatus(userIDList, callback);
取消订阅用户状态
如果您不想接收用户的状态变更通知,您可以调用接口 unsubscribeUserStatus
(Android / iOS & Mac / Windows) 取消订阅用户的状态或清空订阅列表。
如果您不想主动清空订阅列表,当账号离线或者退出登录后,SDK 默认延迟一段时间后自动清空订阅列表。 取消订阅用户状态的接口限制,跟 订阅用户状态 接口限制一致,详情请参考上文。 示例代码如下所示:
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) {
}
});
[V2TIMManager.sharedInstance unsubscribeUserStatus:@[@"userid1", @"userid2", @"userid3"] succ:^ {
} fail:^(int code, NSString *desc) {
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMStringVector userIDList;
userIDList.PushBack(u8"userid1");
userIDList.PushBack(u8"userid2");
auto callback = new Callback{};
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->UnsubscribeUserStatus(userIDList, callback);
状态变更通知
根据您希望感知用户状态的用户类型,可以将状态变更分为 3 种类型:
1. 感知自己的状态变更。
2. 感知好友的状态变更。
3. 感知用户(非好友)的状态变更。
自己的状态变更通知
如果您提前调用 addIMSDKListener
添加了 SDK 监听器,设置成功后,当自己的状态发生变更时,会触发 onUserStatusChanged
回调,您可以在其中获取到自己的最新状态。
好友的状态变更通知
1. 如果您在控制台开启了Set user status query and status change notification
,当好友的状态发生变更时,会自动触发 onUserStatusChanged
回调。 2. 如果您没有开启 Set user status query and status change notification
,并且仍然想感知好友的状态变更,您需要调用 subscribeUserStatus
主动订阅好友的状态。当好友的状态发生变更时,会自动触发 onUserStatusChanged
回调。subscribeUserStatus
的使用有限制,详情请参见上文的 订阅用户状态。 3. 如果您既没有开启好友状态自动通知,也没有调用 subscribeUserStatus
主动订阅好友状态,那么当好友状态发生变更时,您将无法感知到。
普通用户(非好友)的状态变更
如果您希望感知普通用户(非好友)的状态变更,只能调用 subscribeUserStatus
主动订阅。当该用户状态发生变更时,会触发 onUserStatusChanged
回调。subscribeUserStatus
的使用有限制,详情请参见上文的 订阅用户状态。 示例代码如下:
private void initListener() {
V2TIMSDKListener v2TIMSDKListener = new V2TIMSDKListener() {
@Override
public void onUserStatusChanged(List<V2TIMUserStatus> userStatusList) {
String myselfUserID = V2TIMManager.getInstance().getLoginUser();
for (V2TIMUserStatus item : userStatusList) {
if (item.getUserID().equals(myselfUserID)) {
} else {
}
}
}
};
V2TIMManager.getInstance().addIMSDKListener(v2TIMSDKListener);
}
[V2TIMManager.sharedInstance addIMSDKListener:self];
- (void)onUserStatusChanged:(NSArray<V2TIMUserStatus *> *)userStatusList {
NSString *myselfUserID = V2TIMManager.sharedInstance.getLoginUser;
for (V2TIMUserStatus *userStatus in userStatusList) {
if ([userStatus.userID isEqualToString:myselfUserID]) {
} else {
}
}
}
class SDKListener final : public V2TIMSDKListener {
public:
SDKListener() = default;
~SDKListener() override = default;
void OnUserStatusChanged(const V2TIMUserStatusVector& userStatusList) override {
V2TIMString myselfUserID = V2TIMManager::GetInstance()->GetLoginUser();
for (size_t i = 0; i < userStatusList.Size(); ++i) {
if (myselfUserID == userStatusList[i].userID) {
} else {
}
}
}
};
SDKListener sdkListener;
V2TIMManager::GetInstance()->AddSDKListener(&sdkListener);
状态变更通知多端同步
接口限制
套餐包限制
setSelfStatus
接口不限制进阶版。
getUserStatus
查询自己的状态,不限制进阶版。
getUserStatus
除了查询自己外的其他能力,均需要升级到进阶版。
subscribeUserStatus
/ unsubscribeUserStatus
接口的所有能力,均需要升级到进阶版。
接口限频
setSelfStatus
接口不限频。
getUserStatus
查询自己的状态,不限频。
getUserStatus
除了查询自己的状态外,默认限制 5 秒 20 次请求,单次查询最大用户数不超过 500。
subscribeUserStatus
接口,默认限制 5 秒 20 次请求,单次订阅最大用户数不超过 100。
unsubscribeUserStatus
接口,默认限制 5 秒 20 次请求,单次取消订阅最大用户数不超过 100。
常见问题
调用订阅/取消订阅接口时,接口提示 “72001” 的错误码
72001 错误码表示在控制台上并没有开启对应的能力,请登录 控制台 打开对应的功能开关。
本页内容是否解决了您的问题?