功能描述
React Native IM SDK 提供了用户状态管理的功能,每个用户都可拥有两种不同类型的状态:
普通状态:SDK 内置状态,客户无法直接修改。
自定义状态:客户自定义的状态,可以自行修改。利用自定义状态,您可以对该账号设置诸如“听歌中”、“通话中”等一些自定义信息。
注意:
用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询或者按设备设置状态。
用户的普通状态类型有以下三种:
在线:当前用户已登录上线,可以正常收发消息。
离线:用户未主动调用
logout
退出登录,但长连接中断的状态。通常情况下,此时可以接收到离线推送的消息。未登录:用户注册账号后从未登录过,或者用户主动调用
logout
退出登录。关于离线状态,需要注意的是:
1. App 登录过程中杀进程或者网络异常中断(例如 4G/Wifi 切换、电梯信号弱等),此时账号会处于离线状态。
2. App 登录后按 Home 键进入后台,如果 App 进程被系统 kill,此时账号会处于离线状态。如果 App 进程处于后台保活,此时账号仍然是在线状态。
3. 在线/离线的状态切换,依赖于 IMSDK 与后台服务之间的 TCP 长连接。当客户端处于飞行模式、网络彻底中断或者某些设备厂商不支持时,可能会出现 TCP 协议的 FIN 包或 RST 包无法发出的现象,从而导致无法立即切换成离线状态。但由于后台服务接收不到心跳包,400 秒后依然会将当前用户状态设置为离线状态。
设置自己的自定义状态
您可以调用接口 setSelfStatus 设置自己的自定义状态。
如果您在 initSDK 时添加了 SDK 监听器,设置成功后会触发 onUserStatusChanged回调。
onUserStatusChanged
的使用参见下文的 状态变更通知。自定义状态清除机制:
1. 您可以在调用
setSelfStatus
接口时,设置为空来主动清除状态。2. 当 SDK 监测到当前账号处于离线状态后,会自动清除自定义状态,此时也会触发状态变更通知。
说明
调用
setSelfStatus
不需要升级到旗舰版,也无需开启控制台开关。本接口不做限频控制。
示例代码如下所示:
import { TencentImSDKPlugin } from 'react-native-tim-js';const status = 'listening to music'; // 设置为空则表示清楚状态TencentImSDKPlugin.v2TIMManager.setSelfStatus(status);
查询用户状态
查询自己的状态
调用
getUserStatus
,设置 userIDList
仅包含自己的 userID,可查询自己的状态。查询其他人的状态
设置
userIDList
为其他人的 userID 列表,可查询其他人的状态。说明
查询其他用户状态需要升级到旗舰版套餐,详情请参见 基础服务详情。
查询其他用户状态需要提前在 即时通信 IM 控制台 开启 “用户状态查询及状态变更通知”。不开启,调用
getUserStatus
会报错。
接口限频默认为 5 秒 20 次请求,单次查询最大用户数不超过 500 人。
订阅用户状态
您可以调用接口
subscribeUserStatus
订阅指定用户的状态。IM SDK 默认只支持订阅 200 个用户,当超过限制后,会淘汰掉最早订阅的用户。
当您所订阅的用户状态变更时(包括普通状态和自定义状态),您可以在 onUserStatusChanged 回调中收到该用户的状态变更通知。接口特性:
1. 该接口不支持订阅自己的状态。如果您想感知自己的状态变更,可直接监听
onUserStatusChanged
回调。详情请参见下文的 状态变更通知。2. 该接口支持订阅好友的状态,订阅好友会占用上述 200 个用户的名额。
如果您关心所有好友的状态,不需要调用本接口,直接在 即时通信 IM 控制台 开启好友状态自动通知开关,开启后可以在
onUserStatusChanged
回调中收到所有好友的状态变更通知。好友状态自动通知开关如下图所示:
说明
接口限频默认为 5 秒 20 次请求,单次订阅最大用户数不超过 100 人。
如果您需要订阅好友列表的状态,您只需要在控制台上打开开关即可,无需调用该接口。
订阅列表有个数限制,超过限制后,会自动淘汰最先订阅的用户。
示例代码如下所示:
import { TencentImSDKPlugin } from 'react-native-tim-js';const userIDList = ["userid1", "userid2", "userid3"];TencentImSDKPlugin.v2TIMManager.subscribeUserStatus(userIDList);
取消订阅用户状态
如果您不想接收用户的状态变更通知,您可以调用接口
unsubscribeUserStatus
取消订阅用户的状态或清空订阅列表。
如果您不想主动清空订阅列表,当账号退出登录后,IM 后台默认延迟一段时间后自动清空订阅列表。示例代码如下所示:
import { TencentImSDKPlugin } from 'react-native-tim-js';const userIDList = ["userid1", "userid2", "userid3"];TencentImSDKPlugin.v2TIMManager.unsubscribeUserStatus
(userIDList);
状态变更通知
根据您希望感知用户状态的类型,可以将状态变更分为 3 种:
1. 感知自己的状态变更。
2. 感知好友的状态变更。
3. 感知用户(非好友)的状态变更。
自己的状态变更通知
好友的状态变更通知
1. 如果您在 即时通信 IM 控制台 开启了好友状态自动通知,当好友的状态发生变更时,会自动触发
onUserStatusChanged
回调。2. 如果您没有开启好友状态自动通知,但仍然想感知好友的状态变更,需调用
subscribeUserStatus
主动订阅好友状态。当好友的状态发生变更时,会自动触发 onUserStatusChanged
回调。3. 如果您既没有开启好友状态自动通知,也没有调用
subscribeUserStatus
主动订阅好友状态,那么当好友状态发生变更时,您将无法感知到。普通用户(非好友)的状态变更
如果您希望感知普通用户(非好友)的状态变更,只能调用
subscribeUserStatus
主动订阅。当该用户状态发生变更时,会触发 onUserStatusChanged
回调。状态变更通知多端、多实例同步
如果您开启了多端或同平台多实例登录(详情请参见 多端或同平台多实例登录),同一个账号可以在不同设备上登录。当其中一个设备上所登录的用户的自定义状态发生变更时,IM 后台会给其他登录的设备也下发状态变更通知。
接口限制
套餐包限制
setSelfStatus
接口不限制旗舰版。getUserStatus
查询自己的状态,不限制旗舰版。getUserStatus
除了查询自己的状态外,均需要升级到旗舰版。subscribeUserStatus
/ unsubscribeUserStatus
接口的所有能力,均需要升级到旗舰版。接口限频
setSelfStatus
接口不限频。getUserStatus
查询自己的状态,不限频。getUserStatus
除了查询自己的状态外,默认限制 5 秒 20 次请求,单次查询最大用户数不超过 500。subscribeUserStatus
接口,默认限制 5 秒 20 次请求,单次订阅最大用户数不超过 100。unsubscribeUserStatus
接口,默认限制 5 秒 20 次请求,单次取消订阅最大用户数不超过 100。常见问题
调用订阅/取消订阅接口时,接口提示 “72001” 的错误码