常规集成(无 UI 库)

服务端 API

小程序直播 SDK API

最近更新时间:2020-07-06 11:09:40

直播电商解决方案组件是对直播带货场景中使用即时通信 IM 能力的二次封装,在封装基本的收发消息能力的同时,针对直播带货场景封装了点赞、送礼、商品推送、优惠券领取等相关的能力。相关 SDK 下载,请参见 SDK 下载

场景效果

组件使用前置条件

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

SDK 接入

  • 引入 IM SDK
    npm i tim-wx-sdk --save
  • 引入直播带货 SDK
    npm i im-live-sells --save

组件参数

参数 描述
SDKAppID 即时通信 IM 的应用 ID,SDKAppID 需在 即时通信 IM 控制台 上创建,新建的应用默认为体验版,主要用于集成及测试环节。产品正式上线前,建议 购买 旗舰版或专业版。
userSig 即时通信 IM 用户签名,UserSig 为登录即时通信 IM SDK 的必要参数,可在业务后台生成后返回给前端使用,生成文档与代码请参见 生成 UserSig
roomID 直播间群聊房间 ID,此 ID 为即时通信IM所创建的直播群(AVChatRoom)群组 ID,该房间无加入人数限制可通过 即时通信 IM 控制台 创建,或通过 REST API 创建。
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(extension?:string)

给主播点赞。

说明:

extension:点赞时的附加信息,如用户等级。

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

gift(extension?:string)

给主播送礼。

说明:

extension:送礼时的附加信息,如礼物信息等。

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

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 tls.sendCustomMsgAndEmitEvent('eventName','someExtension')

内置对象

TIM 通过 TIM.create 创建的对象,可使用 TIM 所有的方法。

事件

EVENT 描述
TLS.EVENT.SDK_READY 组件已经初始化好,对应于 IM SDK 的 TIM.EVENT.SDK_READY,这个时候才可以调用 SDK 的方法。
TLS.EVENT.JOIN_GROUP 有人加入群聊时触发。
TLS.EVENT.EXIT_GROUP 有人退出群聊时触发。
TLS.EVENT.NOTIFACATION 公告发生修改时触发。
TLS.EVENT.MESSAGE 有人发送群消息时触发。
TLS.EVENT.PROFILE_UPDATE 个人资料发生修改时触发。
TLS.EVENT.ERROR SDK 发生错误时触发。
TLS.EVENT.KICKED 账号其它地方登录时触发。
TLS.EVENT.NETWORK_CHANGE 网络发生改变时触发。
TLS.EVENT.SDK_NOT_READY SDK 不可用时触发。
TLS.EVENT.LIKE 有人给主播点赞时触发。
TLS.EVENT.BUY_GOODS 有人购买商品时触发。
TLS.EVENT.SEND_GIFT 有人给主播送礼时触发。
TLS.EVENT.ATTENT 有人关注主播时触发。
TLS.EVENT.ADD_GOODS 该直播中所推荐的商品发生改变时触发。
TLS.EVENT.USE_COUPON 有人领取优惠券时触发。
目录