im-live-sells

组播带货组件使用文档

直播带货组件是对直播带货场景中使用即时通信IM能力的二次封装，在封装基本的收发消息能力的同时，针对直播带货场景封装了点赞，送礼，商品推送，优惠券领取等相关的能力。

一、组件使用前置条件

• 创建即时通信IM应用
• 创建群自定义字段
  • attent
    • 作用 记录自己关注了哪些主播
• 创建群成员自定义字段
  • add_goods
    • 作用 后台上架新的直播间商品列表
  • room_status
    • 作用 控制直播间状态

二、sdk接入

• 引入IM SDK

npm i tim-js-sdk --save

• 引入直播带货sdk

npm i im-live-sells --save

三、组件参数

• SDKAppID
  • 即时通信应用ID，SDKAppID可在腾讯云即时通信IM控制台上创建应用，SDKAppID可在应用基本信息模块获取，开始创建的应用为体验版，可永久免费试用，但配置有限，不适合正式环境试用。正式环境可购买旗舰版或专业版
• userSig
  • 即时通信IM用户签名，UserSig为登录腾讯云即时通信IM SDK的必要参数，可在业务后台生成后返回给前端使用，生成文档与代码可参考这篇文档
• roomID
  • 直播间群聊房间ID，此ID为即时通信IM所创建的实时音视频（AVCHATROOM）房间ID，该房间无加入人数限制可通过即时通信IM群组管理创建，或通过restapi创建
• TIM
  • 即时通信IM SDK,如是在小程序环境，请使用tim-wx-sdk,web环境则使用tim-js-sdk
• userName
  • 与生成userSig的userName一致

四、初始化示例

import TIMLiveSell from 'im-live-sells'
import TIM from 'tim-js-sdk' //web环境
// import TIM from 'tim-wx-sdk' 小程序环境
const tls = new TIMLiveSell({
      SDKAppID: 1400***803,
      roomID: '@TGS#E****NVLGE',
      userSig: 'eJwtzM9****-reWMQw_',
      userName: 'Ho***st',
      TIM: TIM
})

五、组件回调

• TLS.EVENT.SDK_READY
  • 组件已经初始化好，对应于im sdk的TIM.EVENT.SDK_READY，这个时候才可以调用sdk的方法

tls.on(TLS.EVENT.SDK_READY, async() => {
  
})

• TLS.EVENT.ROOM_STATUS_CHANGE
  • 房间状态改变，如主播上（下）线，暂停等

tls.on(TLS.EVENT.ROOM_STATUS_CHANGE, async(data) => {
  
}

• TLS.EVENT.JOIN_GROUP
  • 有人加入群聊时触发

tls.on(TLS.EVENT.JOIN_GROUP, async(data) => {
  const {nick,avatar,userID} = data
})

• TLS.EVENT.EXIT_GROUP
  • 有人退出群聊时触发

tls.on(TLS.EVENT.EXIT_GROUP, async(data) => {
  const {nick,avatar,userID} = data
})

• TLS.EVENT.NOTIFACATION
  • 公告发生修改时触发

tls.on(TLS.EVENT.NOTIFACATION, async(data) => {
  const { notification } = data
})

• TLS.EVENT.MESSAGE
  • 有人发送群消息时触发
  • 备注：自己发送的消息不会在这个回调里，自己发送的消息上屏请使用sendMessage方法返回的数据，这里与im sdk保持一致。

tls.on(TLS.EVENT.MESSAGE, async(data) => {
  const { nick,avatar,message,userID } = data
})

• TLS.EVENT.LIKE
  • 有人给主播点赞是触发

tls.on(TLS.EVENT.LIKE, async(data) => {
  const { nick,avatar,value,userID } = data
})

• TLS.EVENT.SEND_GIFT
  • 有人给主播送礼时触发

tls.on(TLS.EVENT.SEND_GIFT, async(data) => {
  const { nick,avatar,value,userID } = data
})

• TLS.EVENT.ATTENT
  • 有人关注主播时触发

tls.on(TLS.EVENT.ATTENT, async(data) => {
  const { nick,avatar,value,userID } = data
})

• TLS.EVENT.BUY_GOODS
  • 有人购买商品是触发

tls.on(TLS.EVENT.BUY_GOODS, async(data) => {
  const { nick,avatar,value,userID } = data
})

• TLS.EVENT.USE_COUPON
  • 有人领取优惠券是触发

tls.on(TLS.EVENT.USE_COUPON, async(data) => {
  const { nick,avatar,value,userID } = data
})

• TLS.EVENT.ADD_GOODS
  • 该直播中所推荐的商品发生改变是触发

tls.on(TLS.EVENT.ADD_GOODS, async(data) => {
  const { nick,avatar,value } = data
})

• TLS.EVENT.KICKED
  • 账号其他地方登录时触发

tls.on(TLS.EVENT.KICKED, async() => {
  
})

• TLS.EVENT.NETWORK_CHANGE
  • 网络发生改变时触发

tls.on(TLS.EVENT.NETWORK_CHANGE, async() => {
  
})

• TLS.EVENT.SDK_NOT_READY
  • sdk不可用时触发

tls.on(TLS.EVENT.SDK_NOT_READY, async() => {
  
})

• TLS.EVENT.PROFILE_UPDATE
  • 个人资料发生修改是触发

tls.on(TLS.EVENT.PROFILE_UPDATE, async() => {
  
})

• TLS.EVENT.ERROR
  • sdk发生错误时触发

tls.on(TLS.EVENT.ERROR, async(error) => {
  
})

• ${type}
  • 在调用自定义消息时触发的同名事件

tls.on(`${type}`, async(error) => {
  
})

六、组件方法

• sendMessage(message:string)
  • 方法说明：发送弹幕消息

/**
 * 发送弹幕消息，调用此方法时，群类所有人都可收到该文本消息
 * @method sendMessage
 * @for TLS
 * @param msg 必填 弹幕消息
 * @returns Promise
 */
const {nick,avatar,message} = await tls.sendMessage(msg);

• like(key:string,extension?:string)
  • 方法说明：给主播点赞
  • Key，触发事件的名字
  • extension:点赞时的附加信息，如用户等级

/**
 * 发送点赞消息，调用此方法时，群内所有人都可收到该点赞消息
 * @method like
 * @for TLS
 * @param key 触发事件的名字
 * @param extension 非必填 点赞时附加信息
 * @returns Promise
 *
 */
const {nick,avatar} = await tls.like(key,extension);


//代码示例
const {nick,avatar} =await tls.like('customLike','someData') //用户发送点赞
//监听其他用户点赞
tls.on('customLike',async({extension})=>{
	console.log(extension) // someData
})

• gift(key:string,extension?:string)
  • 方法说明：给主播送礼
  • key 触发事件的名字
  • extension:送礼时的附加信息，如礼物信息等

/**
 * 发送送礼消息，调用此方法时，群内所有人都可收到该送礼消息
 * @method gift
 * @for TLS
 * @param msg 非必填 送礼时附加信息
 * @returns Promise
 */
const {nick,avatar} = await tls.gift(extension);
//代码示例同like方法

• exitRoom()
  • 方法说明：退出直播间

/**
 * 退出房间，主播（群主）不可退出房间
 * @method exitRoom
 * @for TLS
 * @param 
 * @returns Promise
 */
const {status} = await tls.exitRoom();

• joinRoom()
  • 方法说明：加入直播间

/**
 * 加入房间
 * @method joinRoom
 * @for TLS
 * @param 
 * @returns Promise
 */
const {userInfo,groupInfo} = await tls.joinRoom();
const { ownerInfo } = groupInfo;//获取主播信息
const { userID,nick,avatar } = ownerInfo

• getRoomInfo()
  • 方法说明：获取当前房间信息

/**
 * 获取该聊天室的基本信息
 * @method getRoomInfo
 * @for TLS
 * @param 
 * @returns Promise
 */
const {...ownerInfo} = await tls.getRoomInfo();
//ownerInfo 为主播相关信息
const { userID,nick,avatar } = ownerInfo

• attention()
  • 方法说明：关注主播

/**
 * 关注主播
 * @method attention
 * @for TLS
 * @param 
 * @returns Promise
 */
const {nick,avatar} = await tls.attention();

• cancelAttention()
  • 方法说明：取消关注主播

/**
 * 取消关注
 * @method cancelAttention
 * @for TLS
 * @param 
 * @returns Promise
 */
const {nick,avatar} = await tls.cancelAttention();

• destroy()
  • 方法说明：销毁组件

/**
 * 销毁组件
 * @method destroy
 * @for TLS
 * @param 
 * @returns Promise
 */
tls.destroy(); 

• sendCustomMsgAndEmitEvent(eventName: string, extension?: string)
  • 方法说明：发送自定义消息，并触发和type类型的回调事件
  • eventName：事件名
  • extension：自定义消息法人附带信息

/**
 * 发送自定义消息，并触发同名事件
 * @method destroy
 * @for TLS
 * @param eventName:事件名，someExtension：附加信息
 * @returns Promise
 */
await tsl.sendCustomMsgAndEmitEvent('eventName','someExtension')

七、内置对象

• tim 通过TIM.create创建的对象，可使用TIM所有的方法 可参考全部API

/**
 * 对外暴露的实例化好的tim对象，可以直接调用tim下的所有方法
 * 例如：退出登录
 */
this.tls.tim.logout()

八、事件

• EVENT
  • TLS.EVENT.SDK_READY
  • TLS.EVENT.JOIN_GROUP
  • TLS.EVENT.EXIT_GROUP
  • TLS.EVENT.NOTIFACATION
  • TLS.EVENT.MESSAGE
  • TLS.EVENT.PROFILE_UPDATE
  • TLS.EVENT.ERROR
  • TLS.EVENT.KICKED
  • TLS.EVENT.NETWORK_CHANGE
  • TLS.EVENT.SDK_NOT_READY
  • TLS.EVENT.LIKE
  • TLS.EVENT.BUY_GOODS
  • TLS.EVENT.USE_COUPON
  • TLS.EVENT.SEND_GIFT
  • TLS.EVENT.ATTENT
  • TLS.EVENT.ADD_GOODS