本文介绍游客功能的使用限制、实现方法、以及相关参考。

功能介绍

自 v9.8.0 起，圈组支持用户在正式成为服务器成员之前，先以游客身份加入服务器体验相应线上社区的部分内容、活动以及氛围，之后再决策是否需要正式加入服务器。游客相当于临时性的只读普通成员，只能查看服务器和频道内的部分信息，无法发送消息，因此无法与服务器成员形成互动。

以下为对游客支持的功能：

前提条件

根据本文操作前，请确保您已经完成以下操作：

• 开通圈组的游客功能。游客功能需要在开通圈组功能的基础上额外开通后才能使用。
• 用户在以游客身份加入服务器前，需已 登录圈组。

API 调用时序

游客接收消息

游客接收系统通知

游客的查询操作

加入和退出服务器

• 调用 enterAsVisitor 方法以游客身份加入服务器。

  • 单个用户最多只能以游客身份加入 10 服务器。因此，调用该方法时，最多可传入 10 个服务器 ID。如果超限，将以加入失败列表的形式返回。
  • 单个服务器的游客数量上限为 2000。如果超限，将以加入失败列表的形式返回。

  示例代码如下：

  JavaList<Long> serverIds = new ArrayList<>();
  serverIds.add(234567L);
  //以游客身份进入服务器
  QChatEnterServerAsVisitorParam param = new QChatEnterServerAsVisitorParam(serverIds);
  NIMClient.getService(QChatServerService.class).enterAsVisitor(param).setCallback(new RequestCallback<QChatEnterServerAsVisitorResult>() {
      @Override
      public void onSuccess(QChatEnterServerAsVisitorResult result) {
          //进入成功，如果存在进入失败的服务器，failedList 不为空，
          List<Long> failedList = result.getFailedList();
  
      }
  
      @Override
      public void onFailed(int code) {
          //进入失败
      }
  
      @Override
      public void onException(Throwable exception) {
          //进入异常
      }
  });
  

• 调用 leaveAsVisitor 方法退出，调用时最多可传入 10 个服务器 ID。

  游客退出服务器后，订阅的服务器和频道将 自动取消订阅。

  示例代码如下:

  JavaList<Long> serverIds = new ArrayList<>();
  serverIds.add(234567L);
  //以游客身份离开服务器
  QChatLeaveServerAsVisitorParam param = new QChatLeaveServerAsVisitorParam(serverIds);
  NIMClient.getService(QChatServerService.class).leaveAsVisitor(param).setCallback(new RequestCallback<QChatLeaveServerAsVisitorResult>() {
      @Override
      public void onSuccess(QChatLeaveServerAsVisitorResult result) {
          //离开成功，如果存在离开失败的服务器，failedList 不为空，
          List<Long> failedList = result.getFailedList();
  
      }
  
      @Override
      public void onFailed(int code) {
          //离开失败
      }
  
      @Override
      public void onException(Throwable exception) {
          //离开异常
      }
  });
  

消息接收

单个游客加入服务器后，可调用 QChatChannelService#subscribeAsVisitor 方法订阅对其可见的频道，从而在频道成员发送消息后接收消息，否则将无法接收。

示例代码如下:

JavaList<QChatChannelIdInfo> channelIdInfos = new ArrayList<>();
long serverId = 234567L;
long channelId = 543538L;
channelIdInfos.add(new QChatChannelIdInfo(serverId,channelId));
//以游客身份订阅频道
QChatSubscribeChannelAsVisitorParam param = new QChatSubscribeChannelAsVisitorParam(QChatSubscribeOperateType.SUB,channelIdInfos);
NIMClient.getService(QChatChannelService.class).subscribeAsVisitor(param).setCallback(new RequestCallback<QChatSubscribeChannelAsVisitorResult>() {
    @Override
    public void onSuccess(QChatSubscribeChannelAsVisitorResult result) {
        //订阅成功，如果存在订阅失败的频道，failedList 不为空，
        List<QChatChannelIdInfo> failedList = result.getFailedList();

    }

    @Override
    public void onFailed(int code) {
        //订阅失败
    }

    @Override
    public void onException(Throwable exception) {
        //订阅异常
    }
});

系统通知接收

单个游客加入服务器后，可调用 QChatServerService#subscribeAsVisitor 方法订阅服务器，从而能够接收该服务器的部分事件通知，否则将无法接收。也可调用 QChatChannelService#subscribeAsVisitor 方法订阅该服务器下对该游客可见的频道，从而能够接收该频道的部分事件通知，否则将无法接收。

示例代码如下:

JavaList<Long> serverIds = new ArrayList<>();
serverIds.add(234567L);
//以游客身份订阅服务器
QChatSubscribeServerAsVisitorParam param = new QChatSubscribeServerAsVisitorParam(QChatSubscribeOperateType.SUB,serverIds);
NIMClient.getService(QChatServerService.class).subscribeAsVisitor(param).setCallback(new RequestCallback<QChatSubscribeServerAsVisitorResult>() {
    @Override
    public void onSuccess(QChatSubscribeServerAsVisitorResult result) {
        //订阅成功，如果存在订阅失败的服务器，failedList 不为空，
        List<Long> failedList = result.getFailedList();

    }

    @Override
    public void onFailed(int code) {
        //订阅失败
    }

    @Override
    public void onException(Throwable exception) {
        //订阅异常
    }
});

JavaList<QChatChannelIdInfo> channelIdInfos = new ArrayList<>();
long serverId = 234567L;
long channelId = 543538L;
channelIdInfos.add(new QChatChannelIdInfo(serverId,channelId));
//以游客身份订阅频道
QChatSubscribeChannelAsVisitorParam param = new QChatSubscribeChannelAsVisitorParam(QChatSubscribeOperateType.SUB,channelIdInfos);
NIMClient.getService(QChatChannelService.class).subscribeAsVisitor(param).setCallback(new RequestCallback<QChatSubscribeChannelAsVisitorResult>() {
    @Override
    public void onSuccess(QChatSubscribeChannelAsVisitorResult result) {
        //订阅成功，如果存在订阅失败的频道，failedList 不为空，
        List<QChatChannelIdInfo> failedList = result.getFailedList();

    }

    @Override
    public void onFailed(int code) {
        //订阅失败
    }

    @Override
    public void onException(Throwable exception) {
        //订阅异常
    }
});

查询操作

用户在以游客身份加入服务器后，可调用如下方法查询服务器、频道、消息和频道分组的部分信息。

可接收的系统通知

圈组系统通知的类型在 QChatSystemNotificationType 枚举中定义，其中游客可接收的系统通知类型如下：