直播群功能--实时音视频-火山引擎

文档中心

导航

直播群功能

最近更新时间：2024.05.23 11:25:58首次发布时间：2023.05.25 18:20:26

直播群是一种功能强大的群聊工具。相比于普通群聊，其最大成员无上限。直播群成员之间没有固定的强关系，成员可以随时加入或离开。此外，直播群供了更加丰富的功能和工具，帮助用户更好地管理和互动。本文档介绍如何使用 IM SDK 实现直播群功能。你也可以通过阅读代码，了解直播群最佳实践。

API 接口详细文档参看 Android API 参考、iOS API 参考、Web API 参考、微信小程序 API 参考、C++ API 参考。

功能变更日志

自 IM SDK v1.1.0 起支持本功能。
直播群最多创建 200 个。如果超过数量限制，创建新群时会返回错误。建议此时先解散不使用的直播群后再创建新群。
IM SDK Android v1.1.5、iOS v1.1.4、Web v1.1.2、微信小程序 v1.1.2 对本功能做了如下修改：
- 最大成员上限由 10000 人扩充至无上限。默认最大值为 10000 人，如需提高上限，请联系技术支持。
- 支持直播群成员在线状态和人数查询。
- 支持设置消息优先级。
- 支持设置直播群管理员、全员禁言状态下可发言的成员。

前提条件

参看构建基础应用集成使用 IM SDK，版本 v1.1.0 以上。
Web 端需要在创建实例时传入 LivePlugin。

import { BytedIM, LivePlugin } from '@volcengine/im-web-sdk';
const bytedIMInstance = new BytedIM(options, [LivePlugin]);

核心功能

创建直播群

直播群首先需要创建才能正常使用，创建直播群时可以使用 BIMGroupInfo 自定义群名称，群简介，群头像和群公告，创建成功后服务端会保存此直播群信息，客户端不会持久化会话信息。

java

objectivec

TypeScript

cpp

BIMGroupInfo groupInfo = new BIMGroupInfo.BIMGroupInfoBuilder()
        .name(name)
        .description(des)
        .avatarUrl(url)
        .notice(notice)
        .build();

BIMClient.getInstance().getService(BIMLiveExpandService.class).createLiveGroup(groupInfo, new BIMResultCallback<BIMConversation>() {
    @Override
    public void onSuccess(BIMConversation conversation) {
    }

    @Override
    public void onFailed(BIMErrorCode code) {
    }
});

BIMGroupInfo *groupInfo = [[BIMGroupInfo alloc] init];
    groupInfo.name = name;
    groupInfo.desc = desc;
    groupInfo.avatarURL = avatarURL;
    groupInfo.notice = notice;
    [[BIMClient sharedInstance] createLiveGroup:groupInfo completion:^(BIMConversation * _Nonnull conversation, BIMError * _Nullable error) {
            
    }];

import { im_proto } from '@volcengine/im-web-sdk';
const { ConversationType } = im_proto;

const {payload: conversation} = await bytedIMInstance.createConversation({
  participants: [],
  type: ConversationType.MASS_CHAT,
  name,
})

class CreateGroupCallback: public BIM::ResultCallback<BIM::Conversation> {
public:
    void onFailed(BIM::Error error) override { /* ... */ }
    void onSuccess(BIM::Conversation result) override { /* ... */ }
};

// 创建直播群所需信息
auto name = "直播群名称";
auto desc = "直播群描述";
auto notice = "直播群公告";
auto avatarUrl = "直播群头像";

CreateGroupCallback* callback = new CreateGroupCallback();
BIM::GroupInfo info = { name, desc, notice, avatarUrl, {} };
bimClient->getLiveGroupExpandService()->createLiveGroup(info, callback);

加入直播群

当前客户端仅支持加入一个直播群，如需加入其他直播群需先退出前一个加入的直播群，加入直播群时需同时设置当前群的消息监听，事件监听和会话信息变更监听。直播群进入成功后监听生效，仅接受当前直播群消息、事件、会话变更回调，退出后所有监听失效。

java

objectivec

TypeScript

cpp

/**
 * @param conversationShortId      直播群 shortId。
 * @param messageListener          直播群首发消息回调。
 * @param memberEventListener      直播群成员事件回调监听方。
 * @param conversationListListener 直播群会话更新回调。
 * @param callback                 结果回调。
 * @brief 加入直播群，加入直播群后可以收发当前群的信息，直播群不提供本地存储。
 */
BIMClient.getInstance().getService(BIMLiveExpandService.class).joinLiveGroup(conversationShortId, messageListener, memberEventListener, conversationListListener, new BIMResultCallback<BIMConversation>() {

    @Override
    public void onSuccess(BIMConversation conversation) {
 
    }

    public void onFailed(BIMErrorCode code) {

    }
});

class JoinGroupCallback: public BIM::ResultCallback<BIM::LiveGroupJoinResult> {
public:
    void onFailed(BIM::Error error) override { /* ... */ }
    void onSuccess(BIM::LiveGroupJoinResult result) override { /* ... */ }
};

JoinGroupCallback* callback = new JoinGroupCallback();

// conversationShortId 为创建直播群群成功时返回的conversationShortId、或查询所有直播群得到的conversationShortId
bimClient->getLiveGroupExpandService()->joinLiveGroup(conversationShortId, callback);

离开直播群

离开直播群后，所有直播群监听将不会收到此直播群的回调，如需切换直播群可先退出当前直播群，再加入其他直播群。

java

objectivec

TypeScript

cpp

BIMClient.getInstance().getService(BIMLiveExpandService.class).leaveLiveGroup(conversationShortId, new BIMSimpleCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(BIMErrorCode code) {

    }
});

class JoinGroupCallback: public BIM::ResultCallback<BIM::LiveGroupJoinResult> {
public:
    void onFailed(BIM::Error error) override { /* ... */ }
    void onSuccess(BIM::LiveGroupJoinResult result) override { /* ... */ }
};

JoinGroupCallback* callback = new JoinGroupCallback();

// conversationShortId 为创建直播群群成功时返回的conversationShortId、或查询所有直播群得到的conversationShortId
bimClient->getLiveGroupExpandService()->joinLiveGroup(conversationShortId, callback);

发送消息

直播群发送文本消息示例代码如下。

java

objectivec

TypeScript

cpp

BIMMessage msg = BIMClient.getInstance().createTextMessage(text);
BIMClient.getInstance().getService(BIMLiveExpandService.class).sendLiveGroupMessage(msg, bimConversation, new BIMSendCallback() {

    @Override
    public void onSuccess(BIMMessage bimMessage) {
     
    }

    @Override
    public void onError(BIMMessage bimMessage, BIMErrorCode code) {
    }
});

const message = await bytedIMInstance.createTextMessage({
      conversation: conversation,
      content: JSON.stringify({ text: "hello" }),
});
const resp = await bytedIMInstance.sendMessage({ message });

class CustomSendCallback: public BIM::SendCallback {
    void onSuccess(BIM::Message message) override {}
    void onFailed(BIM::Message message, BIM::Error error) override {}
};

//创建消息
auto bimMessage = bimClient->createTextMessage("消息内容");

//发送消息
CustomSendCallback* sendCallback = new CustomSendCallback();
bimClient->getLiveGroupExpandService()->sendLiveGroupMessage(message, *this->mGroup, sendCallback);

接收消息

直播群接收到的消息通过加入直播群设置的消息监听 onReceiveMessage 返回。
建议在加入直播群前（例如 SDK 实例 init 前）执行订阅操作。

说明

与普通群不同，直播群 SDK 内本身仅回调事件，不会存储消息，请在收到回调后自行存储到视图中。

java

objectivec

TypeScript

cpp

/**
 * @type callback
 * @brief 消息监听方。
 */
public interface BIMLiveMessageListener {
    /**
     * @type callback
     * @brief 收到新消息。
     * @param message 消息体。
     */
    void onReceiveMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 发送消息入库完成。
     * @param message 消息体。
     */
    void onSendMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 收到的消息被删除。
     * @param message 消息体。
     */
    void onDeleteMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 收到的消息被修改。（内容+扩展）
     * @param message 消息体。
     */
    void onUpdateMessage(BIMMessage message);
}

[[BIMClient sharedInstance] addMessageListener:<#(nonnull id<BIMLiveMessageListener>)#>];

/// 收到新消息
- (void)onReceiveMessage:(BIMMessage *)message {
    
}

/// 收到消息被删除
- (void)onDeleteMessage:(NSString *)msgID {

}

/// 消息被修改（内容+扩展）
- (void)onUpdateMessage:(BIMMessage *)message {
    
}

/// 发送消息请求前调用。
- (void)onSendMessage:(BIMMessage *)message {
    
}

import { IMEvent, im_proto } from '@volcengine/im-web-sdk';
const { ConversationType } = im_proto;

// 订阅事件
const upsertHandle = bytedIMInstance.event.subscribe.(IMEvent.MessageUpsert, msg => {
  if (msg.conversationType === ConversationType.MASS_CHAT) {
     // 处理消息
  }
});

// 退订事件
bytedIMInstance.event.unsubscribe(IMEvent.MessageUpsert, upsertHandle);

class CustomMessageListener: public BIM::LiveGroupMessageListener {
    void onUpdateMessage(BIM::Message message) override {
        // 收到更新消息
    }

    void onDeleteMessage(BIM::Message message) override {
        // 收到删除消息
    }

    void onReceiveMessage(BIM::Message message) override {
        // 收到新消息
    }

    void onSendMessage(BIM::Message message) override {
        // 发送消息
    }
};

CustomMessageListener* messageListener = new CustomMessageListener;
bimClient->getLiveGroupExpandService()->addLiveGroupMessageListener(messageListener);

直播群消息优先级

直播群可以通过设置消息优先级保证重要消息到达率，服务端消息频控如下表所示，超出频控限制而被拦截的消息不会返回错误，不会下推到客户端。

消息优先级	BIMMessagePriority	消息频控
低	LOW	共用频控阈值为 30 条/秒
中	NORMAL	共用频控阈值为 30 条/秒
高	HIGH	10 条/秒

java

objectivec

TypeScript

cpp

/**
 * @param message      发送的消息
 * @param conversation 会话信息
 * @param priority     设置消息优先级
 * @param callback     结果回调。
 * @brief 发送直播群消息。
 */
public void sendLiveGroupMessage(final BIMMessage message, BIMConversation conversation, BIMMessagePriority priority, final BIMSendCallback callback)

/**
 * @brief 发送直播群消息。
 * @param message 消息体。
 * @param shortId 会话 shortId。
 * @param priority     设置消息优先级
 * @param completion 完成回调
 */
[[BIMClient sharedInstance] sendLiveGroupMessage:message conversation:conversationID priority:priority completion:^(BIMMessage * _Nullable message, BIMError * _Nullable error) {
    
}];

import { im_proto } from '@volcengine/im-web-sdk';
const { MessagePriority } = im_proto;
const message = await bytedIMInstance.createTextMessage({
    conversation: conversation,
    content: JSON.stringify({ text: "hello" }),
});
// 以低优先级发送
const resp = await bytedIMInstance.sendMessage({ 
    message,
    priority: MessagePriority.LOW
});

class CustomSendCallback: public BIM::SendCallback {
    void onSuccess(BIM::Message message) override {}
    void onFailed(BIM::Message message, BIM::Error error) override {}
};

//创建消息
auto bimMessage = bimClient->createTextMessage("消息内容");
//指定优先级
auto priority = BIM::MessagePriority::MSG_PRIORITY_NORMAL;

//发送消息
CustomSendCallback* sendCallback = new CustomSendCallback();
bimClient->getLiveGroupExpandService()->sendLiveGroupMessage(message, *this->mGroup,priority , sendCallback);

其他

直播群还支持如下功能，API 接口详细文档参看 Android API 参考、iOS API 参考、Web API 参考、微信小程序 API 参考、C++ API 参考。

获取直播群在线用户列表
获取当前应用下的所有直播群列表
设置直播群进群黑名单
设置直播群禁言
设置直播群信息
转让群主
解散直播群
踢出在线群成员