跳到主要内容
版本：5.X

直播间场景实践

准备工作​

在开始之前，请确保已创建应用并完成客户端 SDK 集成。

直播间状态管理​

直播间状态通常包括：待开始、直播中、暂停、结束、回放中。直播间状态由业务侧进行维护。

游客模式​

适用场景：未在业务册注册登录的用户进入直播间。

建议通过注册用户获取 Token 连接融云，并在业务侧限制游客是否可以发送消息。

创建并加入聊天室​

  1. 应用服务端通过 Server API 创建聊天室，客户端获取聊天室 ID 后可加入聊天室。
  2. 默认同一用户不能同时加入多个聊天室，可在控制台启用单个用户加入多个聊天室。
  3. 加入聊天室时可通过客户端 SDK 获取最新的历史消息（默认 10 条，最多 50 条），您无法通过客户端 SDK 拉取指定的消息类型， 但可在控制台设置加入聊天室获取的指定消息。 如需拉取更多消息，可开启聊天室消息云存储。

示例代码：

Java
RongCloud rongCloud = RongCloud.getInstance("appKey", "appSecret");
//自定义 api地址方式
//RongCloud rongCloud = RongCloud.getInstance(appKey, appSecret,api);
Chatroom chatroom = rongCloud.chatroom;
ChatroomDataModel chatroomDataModel = new ChatroomDataModel().setId("chatroomId3");
ResponseResult result2 = chatroom.createV2(chatroomDataModel);
System.out.println("createV2:  " + result2.toString());

常见问题：

  • 客户端是否支持直接创建聊天室？ 不支持，仅服务端可创建聊天室。
  • 用户未加入聊天室也能发送消息？ 默认允许，开启 SDK 用户不在聊天室中不能发送消息功能后，则需加入聊天室才能发送消息。
  • 用户加入或退出聊天室时，其他聊天室成员是否有感知？ 默认无感知，但您可以通过聊天室成员变化监听功能，开启后用户加入、退出聊天室后，向其他聊天室成员发送回调通知。您可以在控制台可以免费开启此功能，开启 15 分钟后生效。
  • 用户多端登录时，其中 1 台设备退出聊天室后，别的设备不会同时退出吗？ 默认不会。如您需其他端都退出，可以在控制台免费开启多端同时在线情况下，一端退出聊天室其他端也同步退出聊天室功能，开启 15 分钟后生效。

聊天室销毁（聊天室保活）​

  1. 聊天室具有自动销毁机制，默认 1 个小时内无用户加入或发送消息，会自动将聊天室内所有成员踢出并销毁聊天室，详见聊天室销毁机制。您可调整默认时间销毁时间，最长可设置 24 小时（针对整个 App 设置），设置方式详见调整聊天室销毁等待时间。您也可通过设置“自动销毁类型”来修改销毁时间 ，最长为 7 天 （针对指定聊天室设置），详见设置聊天室自动销毁类型。
  2. 如果您希望聊天室不会自动销毁，可开启聊天室保活服务。您最多可设置 5 个保活的聊天室，如需增加数量，请联系商务。服务开启 15 分钟后生效，详见保活聊天室。此服务在旗舰版需付费使用，尊享版免费使用。
  3. 如果您同时使用了音视频服务，可将聊天室绑定音视频房间。当聊天室达到预设的自动销毁条件时，系统会先检测已绑定的音视频房间（RTCRoomId）是否仍存在：如果绑定的音视频房间仍存在，则阻止聊天室自动销毁；如果绑定的音视频房间已销毁，则直接销毁聊天室。详见绑定音视频房间。

聊天室公告​

适用场景：通过此功能，您可以让用户在直播间列表页面查看每个直播间的公告，或在直播间内看到直播间的公告。

通过聊天室属性管理（KV）实现公告功能：

  1. 加入聊天室。
  2. 通过聊天室属性管理（KV）设置聊天室公告信息。
  3. 客户端通过获取聊天室 KV 属性来获取当前聊天室公告信息。
  4. 通过 KVStatusListener 中的 onChatRoomKVUpdate 事件来同步被更改的聊天室 KV 属性，以达到通知所有聊天室成员的效果。详见添加聊天室 KV 监听器。

客户端示例代码：

Java
// 设置聊天室属性（KV）
String chatRoomId = "聊天室 ID";
// 聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
String key = "自定义了聊天室key";//上下麦状态也可使用聊天室属性（KV） 实现。
// 聊天室属性对应的值，最大长度 4096 个字符
String value = "这是一则聊天室公告";
// true 发送通知; false 不发送。如果发送通知，SDK 会接收到类型标识为 RC:chrmKVNotiMsg 的聊天室属性通知消息（ChatRoomKVNotiMessage），并且消息内容中包含 K，V
boolean sendNotification = false;
// 退出后是否删除
boolean isAutoDel = false;
//通知的自定义字段, sendNotification 为 ture 时有效
String notificationExtra = "通知的自定义字段";

RongChatRoomClient.getInstance().setChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});

//接收端接收：
//在加入聊天室之前设置聊天室属性（KV）状态监听器，
RongChatRoomClient.getInstance().addKVStatusListener(new RongChatRoomClient.KVStatusListener() {
    @Override
    public void onChatRoomKVSync(String roomId) {
        //聊天室属性（KV）列表同步完成时触发。
    }

    @Override
    public void onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap) {
        //onChatRoomKVUpdate 中监听感知 KV 更新
        //聊天室属性（KV）列表更新完成时触发，首次同步 KV 时返回全量 KV，后续触发时仅返回新增、修改的 KV。
    }

    @Override
    public void onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap) {
        //KV 被删除时触发。
    }
});

服务端代码示例：

Java
RongCloud rongCloud = RongCloud.getInstance("appKey", "appSecret");
//自定义 api地址方式
//RongCloud rongCloud = RongCloud.getInstance(appKey, appSecret,api);
ChatroomEntry entry = rongCloud.chatroom.entry;
ChatroomEntryModel model = new ChatroomEntryModel();
model.setChatroomId("chatroomId1");
model.setUserId("userId1");
model.setKey("key1");
model.setValue("value1");
model.setAutoDelete(0);// 可选
model.setObjectName("RC:TxtMsg");// 可选
model.setContent("{\"key1\":\"value1\"}");// 可选

ResponseResult result = entry.set(model);
System.out.println("chatroomEntrySet Result:  " + result.toString());

聊天室消息优先级​

当聊天室消息量较大时，为确保服务器稳定，系统按消息发送的时间顺序丢弃超出消费上限的最新消息，详见抛弃策略。 按重要性划分聊天室消息优先级，建议从高到低依次为：

  1. 打赏、礼物消息，这类消息一般期望直播间的所有用户都能看到。
  2. 文字、语音、图片等消息。
  3. 点赞消息。

您可配置最多 20 个低级别消息类型，当服务器负载高时，系统优先丢弃低级别消息，详见聊天室低级别消息功能。

提示

如果您想保护某个用户发送的消息，可通过聊天室用户白名单功能，使其发送的消息在任何情况下会优先受到保护。 如需保护重要消息，可通过聊天室消息白名单功能功能，使重要消息得到保护。

聊天室礼物与点赞消息​

适用场景：在直播间中发送礼物或者点赞消息。您可通过自定义消息来实现此类型消息。

聊天室礼物消息通用处理机制​

  1. 客户端与业务服务器交互及计费：客户端通过短连接向业务服务器发起请求时，会先触发计费。计费完成后，礼物的发送方可看到 “XXX 送了 XXX 礼物” 的信息。

  2. 计费后的消息发送：完成计费后，系统调用服务端接口来发送自定义的礼物消息。

  3. 连刷礼物场景下的消息处理：对于刷礼物的场景，可能会存在客户点击礼物频率较高的情况。如果按照每条点击触发 1 条消息，可能出现服务端 API 接口超频，消息量过大等问题。

    遇到连刷礼物的情况时，建议对消息进行如下合并处理：

    • 若用户直接选择礼物数量进行刷礼物（例如直接选择 10 个礼物），则仅需发送 1 条消息，同时在参数中带入礼物数量（此处为 10）。
    • 若用户通过连击方式送礼物，且不确定最终连击数量时，可按以下逻辑来合并消息处理：
      • 每 20 个（此数量可根据实际情况自行调整）合并为 1 条消息。
      • 当连击时间超过 1 秒时，发送 1 条消息。例如，若用户连击或者一次性选择 99 个礼物，按照此优化逻辑，仅需发送 5 条消息即可。

  4. 高频小礼物场景，直播页面做排名展示：可使用聊天室属性（KV）实现，App 每隔 0.5 秒统计 1 次点击数量更新到 KV 中，其他聊天室成员通过 KV 查看送礼排行榜。

聊天室点赞消息通用处理机制​

  1. 与礼物消息不同，点赞消息通常不涉及计费，因此可以通过客户端直接发送。
  2. 客户端有发送消息频率限制（5 条/秒）， 因此建议将 1 秒内多次点赞消息合并发送，只发送 1 条消息。 应用服务器可以通过全量消息路由，拿到用户的点赞次数。

发送消息示例详见发送消息文档，礼物消息客户端示例代码如下：

Java
// 注册自定义消息类型，初始化sdk 后注册
ArrayList<Class<? extends MessageContent>> myMessages = new ArrayList<>();
myMessages.add(CustomMessage.class);
RongCoreClient.registerMessageType(myMessages);


// 接收消息示例：设置接收消息监听器，接收消息时会自动回调
RongCoreClient.addOnReceiveMessageListener(
    new io.rong.imlib.listener.OnReceiveMessageWrapperListener() {
        @Override
        public boolean onReceivedMessage(Message message, ReceivedProfile profile) {
        int left = profile.getLeft();
        boolean isOffline = profile.isOffline();
        boolean hasPackage = profile.hasPackage();
        }
});

//返回的 Message 实体参考下面信息，可以使用 objectName 或者 content 来区分消息类型
{
        conversationType = PRIVATE,
                targetId = 'userid3453',
                messageId = 70,
                channelId = '',
                messageDirection = RECEIVE,
                senderUserId = 'userid3453',
                receivedStatus = io.rong.imlib.model.Message$ReceivedStatus @560f848,
                sentStatus = SENT,
                receivedTime = 1739428279001,
                sentTime = 1739428279158,
                objectName = 'gift:CustomMsg',
                content = CustomMessage {
                        giftName = '自定义礼物消息', giftCount = 3
                },
                extra = '',
                readReceiptInfo = io.rong.imlib.model.ReadReceiptInfo @b8d3c06,
                messageConfig = io.rong.imlib.model.MessageConfig @61092c7,
                messageConfig = MessagePushConfig {
                        disablePushTitle = false,
                                pushTitle = '',
                                pushContent = '',
                                pushData = 'null',
                                templateId = '',
                                forceShowDetailContent = false,
                                iOSConfig = null,
                                androidConfig = null,
                                harmonyConfig = null
                },
                canIncludeExpansion = false,
                expansionDic = null,
                expansionDicEx = null,
                mayHasMoreMessagesBefore = false,
                UId = 'CKVO-0J6T-GM26-D3E6',
                disableUpdateLastMessage = 'false',
                directedUsers = '0'
}

服务端示例代码

Java
  RongCloud rongCloud = RongCloud.getInstance("appKey", "appSecret");
//自定义 api地址方式
//RongCloud rongCloud = RongCloud.getInstance(appKey, appSecret,api);
Chatroom chatroom = rongCloud.message.chatroom;
String[] chatroomIds = {"聊天室id"};

GiftCustomTxtMessage ctm = new GiftCustomTxtMessage("自定义礼物",2);
ChatroomMessage chatroomMessage = new ChatroomMessage()
      .setSenderId("1")
      .setTargetId(chatroomIds)
      .setContent(ctm)
      .setObjectName(ctm.getType());

ResponseResult chatroomResult = chatroom.send(chatroomMessage);
System.out.println("send chatroom message:  " + chatroomResult.toString());

具体各端自定义消息类参考：

直播间用户身份与等级​

适用场景：在直播间里显示每个用户的等级、身份等信息。

通过消息体携带用户信息实现用户等级与身份展示。如需通过用户在线时长、点赞、礼物等数据做统计展示用户等级，则需通过回调功能来获取数据源。 例如，通过聊天室状态同步功能获取用户在线时长，通过消息回调功能功能用获取点赞、礼物的数量。

示例代码

Java
// 自定义消息参考礼物消息实现
CustomMessage content = CustomMessage.obtain("消息内容");
UserInfo userInfo=new UserInfo("userId1","userName1", Uri.parse("头像"));
userInfo.setExtra("等级身份等信息");
Message msg = Message.obtain(ROOM_ID, ConversationType.CHATROOM, content);
String pushContent = null;
String pushData = null;
RongCoreClient.getInstance().sendMessage(message, pushContent, pushData, new IRongCoreCallback.ISendMessageCallback() {
    @Override
    public void onAttached(Message message) {
    }

    @Override
    public void onSuccess(Message message) {
    }

    @Override
    public void onError(Message message, IRongCoreEnum.CoreErrorCode coreErrorCode) {
    }
});

在线人数统计与展示​

  1. 业务数据实时统计：通过聊天室状态同步监听用户事件（如加入、退出等）来统计数据。
  2. 给用户展示在线人数：使用聊天室属性（KV）更新在线人数。建议接口调用不要太频繁，几秒 1 次即可。如需获取聊天室在线人数，可通过 Server API 查询聊天室当前人数。
  3. 给用户展示累计观看人次：通过聊天室属性（KV）更新累计人数。 如需统计当下累计观看的人次，您可通过聊天室状态同步进行统计。

直播间在线成员列表和贡献榜单​

  • 成员列表。 您可通过客户端 SDK 的查询聊天室房间信息功能查询指定数量（最多 20 个）的聊天室成员成员的用户 ID 以及他们加入聊天室的时间。
  • 贡献榜单信息。 您可在服务端根据自身业务侧逻辑，计算贡献榜单信息，然后通过设置或更新聊天室属性（KV）来通知聊天室成员。

直播间禁言、封禁（踢人）​

适用场景：根据业务需求限制直播间内用户行为。

聊天室禁言服务​

  1. 通过聊天室全体禁言服务，您可将全体聊天室成员禁言。 该聊天室的所有成员均不能通过客户端 SDK 往该聊天室内发送消息。如需允许部分例外用户， 可将用户加入聊天室禁言用户白名单。 如果聊天室解散，全体禁言数据会被清除。此功能免费。
    提示
    • 聊天室禁言用户白名单优先级高于单个聊天室全体禁言。
    • 聊天室禁言用户白名单优先级低于全局禁言用户。
    • 用户退出聊天室后，白名单状态仍然有效；但是聊天室销毁后再创建，则会失效。
  2. 通过全局禁言用户服务，您可将指定用户在应用下的所有聊天室中禁言， 并设置禁言时长。在禁言时间段内，被禁言用户在应用下的所有聊天室中都无法通过客户端 SDK 发送消息。 您可在控制台开通聊天室全局禁言服务，旗舰版需付费使用，尊享版免费使用。
  3. 通过禁言指定聊天室用户，您可设置指定的 1 个或多个用户在指定聊天室中禁言。App 可使用该功能禁言 App 业务中的聊天室成员，被禁言用户可以接收查看聊天室中其他用户聊天信息，但不能发送消息。并且用户退出聊天室不会使禁言状态失效。此功能功能免费使用。

注意： 您通过融云 Server API 发送聊天室消息接口不受聊天室禁言状态的限制。

客户端设置聊天室禁言监听代码示例：

Java
// 设置禁言监听器
//设置禁言监听器
RongChatRoomClient.addChatRoomNotifyEventListener(
  new RongChatRoomClient.ChatRoomNotifyEventListener() {
      @Override
      public void onChatRoomNotifyMultiLoginSync(ChatRoomSyncEvent event) {
      //在用户在多端登录情况下，在其他客户端加入、退出聊天室
      }

      @Override
      public void onChatRoomNotifyBlock(ChatRoomMemberBlockEvent event) {
      //用户所在聊天室中发生了禁言、解除禁言相关的事件
      }

      @Override
      public void onChatRoomNotifyBan(ChatRoomMemberBanEvent event) {
      //用户所在聊天室发生了封禁用户、解除封禁相关的事件
      }
  });

// Remove

常见问题：

  • 如何实现不让特定用户在任何聊天室里发言？ 您可通过聊天室全局禁言，让特定用户无法在所有聊天室中发言， 被禁言用户可接收查看聊天室中用户聊天信息，但不能发送消息。您可在控制台可以开启聊天室全局禁言功能，旗舰版需付费使用，尊享版免费使用，开启 15 分钟后生效。

聊天室封禁（踢人）功能​

通过封禁聊天室用户功能，您可以在指定聊天室中封禁 1 个或多个用户（同时封禁最多不超过 20 个）。

  • 被封禁时，用户如果在聊天室中，则立即被踢出该聊天室。
  • 被封禁用户在封禁期间内无法加入此聊天室。
  • 封禁时长以分钟为单位，最大值为 43200 分钟，详见封禁聊天室用户。

常见问题：

  • 如何实现让聊天室某些用户不被自动踢出聊天室？ 您可添加用户至白名单来实现此功能，单个聊天室最多支持添加 5 个白名单用户。您可在融云控制台，自行开启聊天室用户白名单。 此功能旗舰版需付费使用，尊享版免费使用，开启 15 分钟后生效。
  • 用户离线了，为什么一直都没被踢出聊天室呢？ 聊天室具有离线成员自动退出机制。用户离线后，如满足以下默认预设条件，融云服务端才会自动将该用户踢出聊天室：
    1. 从用户离线开始 30 秒内，聊天室中产生第 31 条消息时，触发自动踢出。
    2. 用户已离线 30 秒后，聊天室有新消息产生时，触发自动踢出。
    3. 如果不满足上述条件，仍想让用户被踢出聊天室，可以提交工单开启【聊天室成员异常掉线实时踢出】功能。开启该功能后，服务端会通过 SDK 行为判断用户是否处于异常状态，最迟 5 分钟可以将异常用户踢出聊天室。此功能免费。

聊天室封禁用户实例代码示例：

Java
  RongCloud rongCloud = RongCloud.getInstance("appKey", "appSecret");
  Block block = rongCloud.chatroom.block;
  ChatroomMember[] members = {
      new ChatroomMember().setId("user1"),
      new ChatroomMember().setId("user2")
  };
  ChatroomModel chatroom = new ChatroomModel()
      .setId("chatroomid")
      .setMembers(members)
      .setMinute(5);
  ResponseResult result = block.add(chatroom);
  System.out.println("addBlockUser:  " + result.toString());

敏感内容过滤​

适用场景：审核过滤敏感信息，确保消息内容合规。

通过内容审核服务，您可以审核敏感内容。如需通知客户端， 则须在融云控制台开启含敏感词消息屏蔽状态回调发送端功能。 客户端 SDK 监听到消息命中敏感词后，主动获取原始消息并将发送状态置为失败或者处理业务侧逻辑。

客户端发送敏感词拦截监听处理示例:

Java
RongCoreClient.getInstance().setMessageBlockListener(new IRongCoreListener.MessageBlockListener() {
    @Override
    public void onMessageBlock(BlockedMessageInfo info) {
        RongCoreClient.getInstance().getMessageByUid(info.getBlockMsgUId(), new IRongCoreCallback.ResultCallback<Message>() {
            @Override
            public void onSuccess(Message message) {
                //获取本地消息成功
                //设置消息发送状态为失败状态
                message.setSentStatus(Message.SentStatus.FAILED);
                RongCoreClient.getInstance().setMessageSentStatus(message, new IRongCoreCallback.ResultCallback<Boolean>() {
                    @Override
                    public void onSuccess(Boolean aBoolean) {
                        //调用设置消息发送状态方法成功
                    }

                    @Override
                    public void onError(IRongCoreEnum.CoreErrorCode e) {
                        //调用设置消息发送状态方法失败
                    }
                });
            }

            @Override
            public void onError(IRongCoreEnum.CoreErrorCode e) {
                //获取本地消息失败
            }
        });


    }
});

聊天室大喇叭广播​

适用场景：大咖上线通知、送礼全屏全体用户通知、中奖通知、紧急通知等。

您可通过发送全体聊天室广播消息功能功能实现聊天室大喇叭广播。 该消息仅当时在聊天室中的用户可收到，后加入聊天室的用户无法收到。此功能需要在控制台开启聊天室广播消息， 旗舰版付费使用，尊享版免费使用，开启 15 分钟后生效。

聊天室事件更新场景​

适用场景：聊天室中用户的 PK 情况，上下麦状态，对局比分等记录聊天室事件更新等场景。

  1. 在指定聊天室中设置自定义属性。比如在语音直播聊天室场景中，利用此功能记录聊天室中各麦位的属性； 或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。 可以使用聊天室属性管理进行维护，聊天室属性以 Key-Value 的方式进行存储， 支持设置、删除与查询属性，支持批量和强制操作支持客户端配置聊天室属性。每个聊天室最多可设置 100 个 KV。 功能免费。客户端示例代码详见聊天室公告。
  2. 如需实时接收到属性的变更，可以在融云控制台配置聊天室属性自定义回调地址。此功能可在控制台免费开启，开启 15 分钟后生效。
最后于 更新