用户状态订阅 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

用户状态订阅

更新时间： 2024/08/23 18:29:02

NetEase IM SDK（以下简称 NIM SDK）提供订阅用户状态功能，支持订阅/取消订阅用户状态，发布自定义的用户状态，查询用户状态订阅关系等。

技术原理

用户可以通过事件发布以及订阅，来实现 发布-订阅 的设计模式应用于订阅指定用户的在线状态、用户个性化信息订阅等场景。

云信 IM 系统已内置在线状态事件，用户无需发布，由云信服务器管理。

如果内置的在线状态不满足业务需求，您可以按照以下流程发布自定义用户状态个性化实现业务场景。


  flowchart LR
    classDef default fill:#337EFF,stroke:#337EFF,stroke-width:0px,color:#FFFFFF;
    
    A("用户 A 订阅 B subscribeUserStatus")-->B("用户 B 发布自定义状态事件（publishCustomUserStatus）")-->C("A 收到 B 状态变更的回调（onUserStatusChanged）")-->D("按照自身业务逻辑解析处理（invite）")
    click A "https://doc.yunxin.163.com/messaging2/client-apis/zY2MzAxNjQ?platform=client#subscribeuserstatus"
    click B "https://doc.yunxin.163.com/messaging2/client-apis/zY2MzAxNjQ?platform=client#publishcustomuserstatus"
    click C "https://doc.yunxin.163.com/messaging2/client-apis/DAxNjk0Mzc?platform=client#v2nimsubscribelistener"

监听用户状态订阅相关事件

在进行用户状态订阅相关操作前，您可以提前注册相关事件。注册成功后，当相关事件发生时，SDK 会触发对应回调通知。

用户状态订阅相关回调：

onUserStatusChanged：其他用户的用户状态变更回调，包括在线状态和自定义状态。同账号发布状态时，多端也会同步收到回调。

在线状态事件会受到推送的影响：

如果应用被清理，但厂商推送（APNS、小米、华为、OPPO、VIVO、魅族、FCM）可达，则默认不会触发该用户断开连接的事件；若开发者需要该种情况下视为离线，请 前往网易云信控制台>选择应用>IM 即时通讯>功能配置>全局功能>在线状态订阅 进行设置。

Android/iOS/Windows/macOS

调用 addSubscribeListener 方法注册用户状态订阅相关监听器，监听用户状态变更事件。

示例代码：

Android

javaV2NIMSubscribeListener listener = new V2NIMSubscribeListener() {
  @Override
  public void onUserStatusChanged(List<V2NIMUserStatus> userStatusList) {
   //用户状态变更
  }
};
NIMClient.getService(V2NIMSubscriptionService.class).addSubscribeListener(listener);

iOS

objective-c[NIMSDK.sharedSDK.v2SubscriptionService addSubscribeListener:self];
- (void)onUserStatusChanged:(NSArray<V2NIMUserStatus *> *)data {
}

Windows/macOS

cppV2NIMSubscribeListener listener;
listener.onUserStatusChanged = [](nstd::vector<V2NIMUserStatusEvent> events) {
    // handle user status changed event
};
subscriptionService.addSubscribeListener(listener);

如需移除用户相关监听器，可调用 removeSubscribeListener 方法。

Android

javaNIMClient.getService(V2NIMSubscriptionService.class).removeSubscribeListener(listener);

iOS

objective-c[NIMSDK.sharedSDK.v2SubscriptionService removeSubscribeListener:self];

Windows/macOS

cppsubscriptionService.removeSubscribeListener(listener);

Web/uni-app/小程序/Harmony

调用 on("EventName") 方法注册用户状态订阅相关监听器，监听用户状态变更事件。

示例代码：

Web/uni-app/小程序

typescriptnim.V2NIMSubscriptionService.on("onUserStatusChanged", function (userStatusList: Array<V2NIMUserStatus>) {})

如需移除用户相关监听器，可调用 off("EventName") 方法。

typescriptnim.V2NIMSubscriptionService.off("onUserStatusChanged", function (userStatusList: Array<V2NIMUserStatus>) {})

订阅用户状态

调用subscribeUserStatus 方法订阅用户状态，包括在线状态或用户自定义的状态。

成功订阅用户状态后，当订阅的用户状态有变更时，会触发 onUserStatusChanged 回调。

用户状态事件订阅时单向的，双方需要各自自行订阅。
单次最多订阅 100 个用户的状态，可多次调用该接口，订阅更多的用户状态，但是总订阅人数最多为 3000，若超限，则默认删除最老的订阅，即有效订阅最多为 3000 个。
若同一账号多端重复订阅，订阅有效期默认会覆盖（新的覆盖前一次时长）。
若传入的账号 ID 都不存在，则调用接口失败；若部分账号 ID 存在，则调用接口成功。调用结果只返回账号 ID 存在的用户状态，错误的账号 ID 不返回。

示例代码：

Android

javaList<String> accountIds = Arrays.asList("account1", "account2");
//订阅的有效期，时间范围为 60~2592000，单位：秒
long duration = 60L;
//订阅后是否立即同步事件状态值， 默认为false。 为true：表示立即同步当前状态值 但为了性能考虑， 30S内重复订阅，会忽略该参数
boolean immediateSync = false;
V2NIMSubscribeUserStatusOption option = new V2NIMSubscribeUserStatusOption(accountIds, duration, immediateSync);
NIMClient.getService(V2NIMSubscriptionService.class).subscribeUserStatus(option, new V2NIMSuccessCallback<List<String>>() {
  @Override
  public void onSuccess(List<String> failList) {
   //订阅成功,返回订阅失败的failList
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //订阅失败
  }
});

iOS

objective-cV2NIMSubscribeUserStatusOption *option = [[V2NIMSubscribeUserStatusOption alloc] init];
    option.accountIds = @[@"accId1",@"accId2"];
    [NIMSDK.sharedSDK.v2SubscriptionService subscribeUserStatus:option success:^(NSArray<NSString *> *failedList) {
           // 成功回调
        } failure:^(V2NIMError * _Nonnull error) {
            // 失败回调
        }];

Windows/macOS

cppV2NIMSubscribeUserStatusOption option;
option.accountIds.push_back("account1");
subscriptionService.subscribeUserStatus(
    option,
    [](nstd::vector<nstd::string> failedAccounts) {
        // subscribe user status succeeded
    },
    [](V2NIMError error) {
        // subscribe user status failed, handle error
    });

Web/uni-app/小程序

typescripttry {
    const failedAccounts = await nim.V2NIMSubscriptionService.subscribeUserStatus({
        accountIds: ['user1', 'user2'],
        duration: 3600 * 24    
    })
    if (failedAccounts.length > 0) {
       console.error('subscribeUserStatus failed accounts', failedAccounts)       
    }
} catch(err) {
    console.error('subscribeUserStatus err': err)
}

取消订阅用户状态

调用 unsubscribeUserStatus 方法取消用户状态的订阅。

示例代码：

Android

javaList<String> accountIds = Arrays.asList("account1", "account2");
V2NIMUnsubscribeUserStatusOption option = new V2NIMUnsubscribeUserStatusOption(accountIds);
NIMClient.getService(V2NIMSubscriptionService.class).unsubscribeUserStatus(option, new V2NIMSuccessCallback<List<String>>() {
  @Override
  public void onSuccess(List<String> failList) {
   //取消订阅成功,返回取消订阅失败的failList
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //取消订阅失败
  }
});

iOS

objective-cV2NIMUnsubscribeUserStatusOption *option = [[V2NIMUnsubscribeUserStatusOption alloc] init];
    option.accountIds = @[@"accId1",@"accId2"];
    [NIMSDK.sharedSDK.v2SubscriptionService unsubscribeUserStatus:option success:^(NSArray<NSString *> *failedList) {
        // 成功回调
    } failure:^(V2NIMError * _Nonnull error) {
        // 失败回调
    }];

Windows/macOS

cppV2NIMUnsubscribeUserStatusOption option;
option.accountIds.push_back("account1");
subscriptionService.unsubscribeUserStatus(
    option,
    [](nstd::vector<nstd::string> failedAccounts) {
        // unsubscribe user status succeeded
    },
    [](V2NIMError error) {
        // unsubscribe user status failed, handle error
    });

Web/uni-app/小程序

typescripttry {
    const failedAccounts = await nim.V2NIMSubscriptionService.unsubscribeUserStatus({
        accountIds: ['user1', 'user2']
    })
    if (failedAccounts.length > 0) {
       console.error('unsubscribeUserStatus failed accounts', failedAccounts)       
    }
} catch(err) {
    console.error('unsubscribeUserStatus err': err)
}

查询用户状态订阅关系

调用 queryUserStatusSubscriptions 方法查询用户状态订阅关系。

传入账号列表，查询自己订阅了其中哪些账号的状态，调用接口成功后，返回订阅的账号列表。

示例代码：

Android

javaList<String> accountIds = Arrays.asList("account1", "account2");
NIMClient.getService(V2NIMSubscriptionService.class).queryUserStatusSubscriptions(accountIds, new V2NIMSuccessCallback<List<V2NIMUserStatusSubscribeResult>>() {
  @Override
  public void onSuccess(List<V2NIMUserStatusSubscribeResult> v2NIMUserStatusSubscribeResults) {
   //查询成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //查询失败
  }
});

iOS

objective-c[NIMSDK.sharedSDK.v2SubscriptionService queryUserStatusSubscriptions:@[@"accId1",@"accId2"] success:^(NSArray<V2NIMUserStatusSubscribeResult *> *resultList) {
        // 成功回调
    } failure:^(V2NIMError * _Nonnull error) {
        // 失败回调
    }];

Windows/macOS

cppnstd::vector<nstd::string> accountIds;
accountIds.push_back("account1");
subscriptionService.queryUserStatusSubscriptions(
    accountIds,
    [](nstd::vector<nstd::string> subscribedAccounts) {
        // query user status subscribe succeeded
    },
    [](V2NIMError error) {
        // query user status subscribe failed, handle error
    });

Web/uni-app/小程序

typescripttry {
    const result = await nim.V2NIMSubscriptionService.queryUserStatusSubscriptions(['user1', 'user2'])
   console.log('queryUserStatusSubscriptions result', result)       
 } catch(err) {
    console.error('queryUserStatusSubscriptions err': err)
 }

发布用户自定义状态

调用 publishCustomUserStatus 方法发布用户自定义状态。

如果默认在线状态不满足业务需求，可以发布自定义用户状态。

示例代码：

Android

java//自定义设置值： 10000以上，包括一万， 一万以内为预定义值
int statusType = 10001;
//状态的有效期，单位秒，范围为 60s 到 7days
long duration = 60L;
//用户发布状态时设置的扩展字段
String extension = "{\"key\":\"value\"}";
//用户发布状态时是否只广播给在线的订阅者，默认值为TRUE
boolean onlineOnly = true;
// 用户发布状态时是否需要多端同步，默认值为FALSE
boolean multiSync = false;
//自定义用户状态参数
V2NIMCustomUserStatusParams params = new V2NIMCustomUserStatusParams.Builder(statusType,duration)
   .extension(extension)
   .onlineOnly(onlineOnly)
   .multiSync(multiSync)
   .build();
NIMClient.getService(V2NIMSubscriptionService.class).publishCustomUserStatus(params, new V2NIMSuccessCallback<V2NIMCustomUserStatusPublishResult>() {
  @Override
  public void onSuccess(V2NIMCustomUserStatusPublishResult v2NIMCustomUserStatusPublishResult) {
   //发布自定义用户状态成功
  }
}, new V2NIMFailureCallback() {
  @Override
  public void onFailure(V2NIMError error) {
   //发布自定义用户状态失败
  }
});

iOS

objective-c V2NIMCustomUserStatusParams *params = [[V2NIMCustomUserStatusParams alloc] init];
    params.statusType = 10001;
    [NIMSDK.sharedSDK.v2SubscriptionService publishCustomUserStatus:params success:^(V2NIMCustomUserStatusPublishResult *resultList) {
        // 成功回调
    } failure:^(V2NIMError * _Nonnull error) {
        // 失败回调
    }];

Windows/macOS

cppV2NIMCustomUserStatusParams params;
params.statusType = 100001;
subscriptionService.publishCustomUserStatus(
    params,
    []() {
        // publish custom user status succeeded
    },
    [](V2NIMError error) {
        // publish custom user status failed, handle error
    });

Web/uni-app/小程序

typescripttry {
    const result = await nim.V2NIMSubscriptionService.publishCustomUserStatus({
          /**
           * 自定义设置值： 10000以上，不包括一万， 一万以内为预定义值。小于1万，返回参数错误
           */
          statusType: 10001
          /**
           * 状态的有效期，单位秒，范围为 60s 到 7days
           */
          duration: 3600 * 24
          /**
           * 用户发布状态时是否只广播给在线的订阅者。默认为 true
           */
          onlineOnly: false
          /**
           * 用户发布状态时是否需要多端同步。默认为 false
           */
          multiSync: true
    })
   console.log('publishCustomUserStatus result', result)       
 } catch(err) {
    console.error('publishCustomUserStatus err': err)
 }

技术原理

监听用户状态订阅相关事件

订阅用户状态

取消订阅用户状态

查询用户状态订阅关系

发布用户自定义状态

相关信息