VLBIMSDK — 直播间 IM SDK

快速开始

import { VLBIMSDK } from 'vlbim-sdk';

const sdk = new VLBIMSDK();

// 登录（后端下发 userSig）
await sdk.login({ userID, userSig, avatar, username });

// 进入直播间
await sdk.joinGroup(liveId);

// 监听语义化事件
sdk.on(VLBIMSDK.MsgEvent.LIVE_STATUS, (data) => {
  console.log('直播状态变更', data);
});

// 发送评论
await sdk.sendMessage(liveId, { content: '666' });

// 离开直播间
sdk.quitGroup(liveId);

// 页面/应用销毁
sdk.destroy();

构造函数

new VLBIMSDK()

API

连接生命周期

sdk.login(options, onReady?)

登录 TIM 服务。

| 参数 | 类型 | 说明 | |------|------|------| | userID | string | 用户 ID（与后端一致） | | userSig | string | 后端下发的签名 | | avatar | string | 头像 URL | | username | string | 昵称 | | onReady | () => void | SDK 就绪回调（可选，等同于监听 SDK_READY） |

返回值：Promise<any>

sdk.loginAgain()

使用上次凭证重新登录（断线重连时使用）。

sdk.logout()

退出 TIM 登录。返回 Promise<any>。

sdk.destroy()

注销所有监听器，释放 IM 实例资源。应用销毁时必须调用。返回 Promise<any>。

用户信息

sdk.updateUserInfo({ avatar?, username? })

更新头像或昵称

sdk.updateCheckList(checkList: string[])

更新服务端下发的敏感词列表

群组管理

sdk.joinGroup(groupID)

加入直播间 AVChatRoom。

返回 Promise<any>。

sdk.retryGroup()

重新加入上次的直播间（断线重连时使用）。

sdk.quitGroup(groupID)

退出指定群。返回 Promise<any>。

sdk.getGroupOnlineMemberCount(groupID)

获取群在线人数。返回 Promise<any>。

消息发送

sdk.sendMessage(to, options)

发送文本评论消息到指定群（liveId）。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | to | string | 必填 | 目标群 ID（liveId） | | content | string | 必填 | 消息正文 | | isForbidden | number | 0 | 是否被禁言（随消息发送给下游） |

错误码处理：

| 错误码 | 说明 | |--------|------| | 80001 | 内容涉及敏感词，reject { code, message } | | 10017 | 用户已被禁言，reject | | 10010 | 聊天群已解散，reject | | 10015 | 非法群 ID，reject | | 2100 | 未在群内，自动重新 joinGroup 后重试 | | 3000 | 网络异常，reject |

返回值：Promise<parsedMessage | void>

语义化事件订阅

sdk.on(key, callback)

监听事件。同一 key 支持多个 callback，底层监听条目只注册一次。 返回值为当前 callback 的取消订阅函数。

const unsubscribe = sdk.on(VLBIMSDK.MsgEvent.REWARD, (data) => {
  console.log('打赏', data);
});

unsubscribe();

sdk.off(key, callback?)

取消监听。传入 callback 时只移除该 callback；不传 callback 时移除当前 key 下的全部 callback。

MsgEvent 事件常量

评论 / 消息

| 常量 | key | 说明 | |------|-----|------| | NORMAL_MESSAGE | normalMessage | 普通文本评论 | | RED_BAG_PUSHING | redBagPushing | 红包消息 | | COMMENT_DEL | commentDel | 评论被删除 |

直播状态

| 常量 | key | 说明 | |------|-----|------| | LIVE_STATUS | liveStatus | 直播状态变更（开播/暂停/结束） | | LIVE_AUDIT | liveAudit | 直播审核状态变更 | | STREAM_STATUS | streamStatus | 推流状态变更 |

用户动作

| 常量 | key | 说明 | |------|-----|------| | LIVE_ENTER | liveEnter | 用户进入直播间 | | LIVE_SHARE | liveShare | 用户分享直播 | | LIVE_HOT_VALUE_UPDATE | liveHotValueUpdate | 热度值更新 | | LIVE_STAR | liveStar | 星星（点亮） |

禁言 / 拉黑

| 常量 | key | 说明 | |------|-----|------| | FORBIDDEN | forbidden | 个人禁言开关（C2C） | | USER_BLOCK | userBlock | 拉黑开关（C2C） |

示例：

sdk.on(VLBIMSDK.MsgEvent.FORBIDDEN, (data) => {
  if (data.status) console.log('已被禁言');
});

打赏 / 观看奖励

| 常量 | key | 说明 | |------|-----|------| | REWARD | reward | 打赏消息 | | WATCH_REWARD_CHANGE | watchRewardChange | 观看时长奖励变化 |

商品 / 讲解

| 常量 | key | 说明 | |------|-----|------| | UPDATE_PRODUCT_LIST | updateProductList | 商品列表更新 | | RECOMMEND_PRODUCT | recommendProduct | 商品推荐/讲解开始 | | CANCEL_PRODUCT_EXPLAIN | cancelProductExplain | 商品讲解取消 | | CHANGE_PRODUCT_EXPLAIN | changeProductExplain | 商品讲解切换 | | WORKBENCH_PLAY_NEXT | workbenchPlayNext | 工作台切换下一条讲解 | | SALE_ACTIVITY_CHANGE | saleActivityChange | 促销活动变更 | | SHOP_ORDER | shopOrder | 用户下单/购买通知 | | LIVE_SHOP | liveShop | 直播商城信息变更 |

优惠券

| 常量 | key | 说明 | |------|-----|------| | LIVE_COUPON_ACTIVITY | liveCouponActivity | 优惠券活动推送 | | LIVE_COUPON_PUSH_RECEIVE | liveCouponPushReceive | 优惠券定向推送/领取 |

抽奖

| 常量 | key | 说明 | |------|-----|------| | JOIN_DRAW_ACTIVITY | joinDrawActivity | 参与抽奖 | | MANUAL_DRAW_ACTIVITY | manualDrawActivity | 手动开奖 | | LIVE_DRAW_ACTIVITY | liveDrawActivity | 直播抽奖活动状态变更 |

签到

| 常量 | key | 说明 | |------|-----|------| | LIVE_CHECK_IN_CREATE | liveCheckInCreate | 签到活动发起 | | LIVE_CHECK_STATUS_UPDATE | liveCheckStatusUpdate | 签到状态更新 |

问卷

| 常量 | key | 说明 | |------|-----|------| | QUESTIONNAIRE_UPDATE | questionnaireUpdate | 问卷/表单更新 |

文档（横屏直播）

| 常量 | key | 说明 | |------|-----|------| | LIVE_WORD_PAGE | liveWordPage | 文档翻页 | | LIVE_WORD_STATUS | liveWordStatus | 文档开关状态变更 |

系统 / 配置

| 常量 | key | 说明 | |------|-----|------| | SETTING | setting | 直播设置变更（原始，所有 setting 消息） | | SETTING_GIFT | settingGift | 礼物开关变更（data.status: 1=开 2=关） | | SETTING_COMMENT_CENSOR | settingCommentCensor | 评论审核开关变更 | | UPDATE_TEXT_FILTER | updateTextFilter | 违禁词过滤列表更新 | | LIVE_STREAM_ROUTE_CHANGE | liveStreamRouteChange | 直播流线路切换 | | FINISH_PLAYBACK | finishPlayback | 回放生成完成 |

高级用法：使用 SETTING 原始事件 + SETTING_TYPE 常量：

sdk.on(VLBIMSDK.MsgEvent.SETTING, (data) => {
  switch (data.type) {
    case VLBIMSDK.SETTING_TYPE.SHOP:        break;
    case VLBIMSDK.SETTING_TYPE.ORDER_ENTRY: break;
    case VLBIMSDK.SETTING_TYPE.CLEAR_SCREEN: break;
  }
});

SETTING_TYPE 可用值：

| 常量 | 值 | 说明 | |------|----|------| | GIFT | gift | 礼物开关 | | COMMENT_CENSOR | commentCensor | 评论审核 | | LOW_LATENCY | lowLatency | 低延迟模式 | | AD_CONFIG | ad-config | 广告配置 | | SHOP | shop | 商城开关 | | USER_WATCH_COMMENTS | userWatchComments | 观众评论可见设置 | | COUPON | coupon | 优惠券功能开关 | | PROMOTION | promotion | 推广功能开关 | | ORDER_ENTRY | orderEntry | 下单入口开关 | | GOODS | goods | 商品开关 | | AUTH_EXPIRE | authExpire | 授权过期规则 | | SHOP_DIRECTION | shopDirection | 商城导购方向 | | CLEAR_SCREEN | clearScreen | 清屏 | | RED_PACKET | redPacket | 红包功能开关 |

注意事项

1. joinGroup() 须在登录就绪后调用：
2. destroy() 必须在页面/应用销毁时调用：防止内存泄漏。
3. 敏感词检测：对照 updateCheckList() 下发的列表做前置拦截