tencent cloud

文档反馈

Android & iOS & Mac

最后更新时间:2022-11-28 16:40:30

    功能描述

    从 6.3 版本开始,IMSDK 提供了用户状态管理的功能,每个用户拥有两种不同类型的状态:

    • 普通状态。SDK 内置状态,客户无法直接修改。
    • 自定义状态。客户自定义的状态,可以自行修改。利用自定义状态,您可以对该帐号设置诸如“听歌中”、“通话中”等一些自定义信息。
    说明:

    用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询或者按设备设置状态。

    用户的普通状态类型有以下三种:

    • 在线(ONLINE):当前用户已登录上线,可以正常收发消息。
    • 离线(OFFLINE):用户未主动调用 logout (Android / iOS & Mac / Windows) 退出登录,但长连接中断的状态。通常情况下,此时可以接收到离线推送的消息。
    • 未登录(UNLOGINED):用户注册账号后从未登录过,或者用户主动调用 logout 退出登录。

    关于离线状态,需要注意的是:

    1. App 登录过程中杀进程或者网络异常中断(例如 4G/Wifi 切换、电梯信号弱等),此时账号会处于离线状态。
    2. App 登录后按 Home 键进入后台,如果 App 进程被系统 kill,此时账号会处于离线状态。如果 App 进程处于后台保活,此时账号仍然是在线状态。
    3. 在线/离线的状态切换,依赖于 IMSDK 与后台服务之间的 TCP 长连接。当客户端处于飞行模式、网络彻底中断或者某些设备厂商不支持时,可能会出现 TCP 协议的 FIN 包或 RST 包无法发出的现象,从而导致无法立即切换成离线状态。但由于后台服务接收不到心跳包,400 秒后依然会将当前用户状态设置为离线状态。
    注意:

    • 下文所述的部分功能仅旗舰版客户支持,使用前请确认。
    • 下文所述的部分功能需要在 即时通信 IM 控制台 打开对应的用户状态开关,使用前请确认。

    设置自己的自定义状态

    您可以调用接口 setSelfStatus(Android / iOS & Mac / Windows) 设置 customStatus 字段来设置自己的自定义状态。
    如果您提前调用 addIMSDKListener(Android / iOS & Mac) 添加了 SDK 监听器,设置成功后会触发 onUserStatusChangedAndroid / iOS & Mac / Windows) 回调。详情请参见下文的 状态变更通知

    自定义状态清除机制:

    1. 您可以在调用 setSelfStatus 接口时,通过将 customStatus 字段设置为空来主动清除。
    2. 当 SDK 监测到当前账号处于离线状态后,会自动清除自定义状态,此时也会触发状态变更通知。
    说明:

    1. 调用 setSelfStatus 不需要升级到旗舰版,也无需开启控制台开关。
    2. 本接口不做限频控制。

    接口原型:

    /**
    *  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,可查询自己的状态。

    说明:

    1. 查询自己的状态不需要升级到旗舰版,也无需开启控制台开关。
    2. 查询自己的状态不做接口限频控制。

    示例代码:

    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) 回调中收到该用户的状态变更通知。

    接口特性:

    1. 该接口不支持订阅自己的状态。如果您想感知自己的状态变更,可直接监听 onUserStatusChanged 回调。详情请参见下文的 状态变更通知

    2. 该接口支持订阅好友的状态,但是订阅好友也会占用上述 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 种类型:

    1. 感知自己的状态变更。
    2. 感知好友的状态变更。
    3. 感知用户(非好友)的状态变更。

    上述 3 种方式的状态变更通知,都是通过 onUserStatusChanged (Android / iOS & Mac / Windows) 回调出来。
    回调原型:

    /**
    * 用户状态变更通知
    *
    * @note 收到通知的情况:
    * 1. 订阅过的用户发生了状态变更(包括在线状态和自定义状态),会触发该回调
    * 2. 在 IM 控制台打开了好友状态通知开关,即使未主动订阅,当好友状态发生变更时,也会触发该回调
    * 3. 同一个账号多设备登录,当其中一台设备修改了自定义状态,所有设备都会收到该回调
    */
    public void onUserStatusChanged(List<V2TIMUserStatus> userStatusList){}
    

    虽然状态通知都通过 onUserStatusChanged 抛出,但不同类型的用户触发该通知的方式不同。

    自己的状态变更通知

    如果您提前调用 addIMSDKListener 添加了 SDK 监听器,设置成功后会,当自己的状态发生变更时,会触发 onUserStatusChanged 回调,您可以在其中获取到自己的最新状态。

    好友的状态变更通知

    1. 如果您在 即时通信 IM 控制台 开启了好友状态自动通知,那么当好友的状态发生变更时,会自动触发 onUserStatusChanged 回调,您可以在其中获取到好友的最新状态。

    2. 如果您没有开启好友状态自动通知,并且仍然想感知好友的状态变更,您需要调用 subscribeUserStatus 主动订阅好友的状态。当好友的状态发生变更时,会自动触发 onUserStatusChanged 回调。

    注意:

    subscribeUserStatus 仅旗舰版客户支持,并且需要开启控制台开关。详情请参见上文的 订阅用户状态

    1. 如果您既没有开启好友状态自动通知,也没有调用 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“ 的错误码

    72001 错误码表示在控制台上并没有开启对应的能力,请登录 即时通信 IM 控制台 打开对应的功能开关。

    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持