# 组件接口

名称 功能说明
订阅组件 subscribe 订阅组件可配置到小程序页面上,可对一场未开播的直播进行单次订阅,开播时会自动下发开播提醒给用户
挂件组件 pendant 挂件可配置在小程序页面上,用户可通过挂件进入当前小程序对应直播间
获取单次订阅状态  getSubscribeStatus 在直播组件版本 1.3.0 及以上版本通过该接口获取直播间单次订阅状态
获取直播状态  getLiveStatus 首次获取立马返回直播状态,往后间隔1分钟或更慢的频率去轮询获取直播状态
获取用户 openid 参数getOpenid 在直播组件版本 1.3.0 及以上版本通过该接口获取用户 openid 参数
获取分享卡片链接参数getShareParams 在直播组件版本 1.3.0 及以上版本通过该接口获取以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系
直播小窗控制参数 close_picture_in_picture_mode 通过参数设置是否关闭小窗
携带参数( 直播间到商详页面, 从群分享卡片返回直播间) 直播组件版本 1.3.0 及以上支持携带以下参数,可用这些参数建立用户、直播间、商品之间的映射关系。

# 1. 【订阅】组件(注:若要使用该组件,需在主包/分包先引入直播组件)

功能解释:订阅组件可配置到小程序页面上,可对一场未开播的直播进行单次订阅,开播时会自动下发开播提醒给用户,无需开发者额外开发

组件使用:如果需要在直播页以外小程序其他页面也有同样的开播提醒的功能,可以引入【订阅】组件 subscribe(开播前才会显示,直播开始后自动消失该组件);需在 page 页面(如 home 页面)的 home.json 引用订阅组件,可通过 stopPropagation 属性控制是否阻止事件冒泡(默认不阻止事件冒泡,stopPropagation 为 false)。

# 示例代码如下:

{
    "usingComponents": {
        "subscribe": "plugin-private://wx2b03c6e691cd7370/components/subscribe/subscribe"
    }
}

然后便可在 home.wxml 里使用订阅组件,其中直播房间 id 可通过下面 获取直播房间列表 API 获取。 同时,订阅组件支持自定义颜色和大小以及携带自定义参数,参数说明如下:

  • room-id:表示房间号,类型为 Number(默认为0)
  • width:表示宽度,类型为 Number(默认为120)
  • height:表示高度,类型为 Number(默认为41)
  • font-size:表示字号,类型为 Number(默认为17)
  • color:表示字体颜色,类型为 String(默认为'FFFFFF')
  • background-color:表示背景色,类型为 String(默认为'#6467F0')
  • custom-params:表示自定义参数,类型为 String(默认为空)
  • stop-propagation:表示阻止事件冒泡,类型为 Boolean(默认为false,不阻止事件冒泡)
// 传参
let roomId = 1
let width = 120
let height = 41
let fontSize = 17
let color = '#FFFFFF'
let backgroundColor = '#6467F0'
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在订阅组件上携带自定义参数(如示例中的 path 和pid参数),后续可以在 App onShow 生命周期的 options 里获取(上限600个字符,超过部分会被截断)
this.setData({
    width,
    height,
    fontSize,
    color,
    backgroundColor,
    customParams
})

// 监听订阅事件用于获取订阅状态
onSubscribe(e) {
    console.log('房间号:', e.detail.room_id)
    console.log('订阅用户openid', e.detail.openid)
    console.log('是否订阅', e.detail.is_subscribe)
}
<subscribe
    room-id="{{roomId}}"
    width="{{width}}"
    height="{{height}}"
    font-size="{{fontSize}}"
    color="{{color}}"
    background-color="{{backgroundColor}}"
    custom-params="{{customParams}}"
    bindsubscribe="onSubscribe">
</subscribe>

# 2.【获取单次订阅状态】接口(注:若要使用该接口,需在主包/分包先引入直播组件)

接口说明:获取直播间单次订阅状态

调用方法:若要调用【获取单次订阅状态】接口 getSubscribeStatus,需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下:

let livePlayer = requirePlugin('live-player-plugin')

// 获取直播间单次订阅状态
const roomId = xxx // 房间 id
livePlayer.getSubscribeStatus({ room_id: roomId })
    .then(res => {
        console.log('房间号:', res.room_id)
        console.log('订阅用户openid', res.openid)
        console.log('是否订阅', res.is_subscribe)
    }).catch(err => {
        console.log('get subscribe status', err)
    })

# 3. 【获取直播状态】接口(注:若要使用该接口,需在主包/分包先引入直播组件)

接口说明:首次获取立马返回直播状态,往后间隔1分钟或更慢的频率去轮询获取直播状态

# 直播状态说明:

  • 101 直播中:表示主播正常开播,直播正常的状态

  • 102 未开始:表示主播还未开播

  • 103 已结束:表示在直播端点击【结束】按钮正常关闭的直播,或直播异常 15 分钟后系统强制结束的直播

  • 104 禁播:表示因违规受到运营处罚被禁播

  • 105 暂停中:表示在 MP 小程序后台 - 控制台内操作暂停了直播

  • 106 异常:表示主播离开、切后台、断网等情况,该直播被判定为异常状态,15 分钟内恢复即可回到正常直播中的状态;如果 15 分钟后还未恢复,直播间会被系统强制结束直播

  • 107 已过期:表示直播间一直未开播,且已达到在 MP 小程序后台创建直播间时填写的直播计划结束时间,则该直播被判定为过期不能再开播

调用方法:若要调用【获取直播状态】接口 getLiveStatus,需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下:

let livePlayer = requirePlugin('live-player-plugin')

// 首次获取立马返回直播状态
const roomId = xxx // 房间 id
livePlayer.getLiveStatus({ room_id: roomId })
    .then(res => {
        // 101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常,107:已过期 
        const liveStatus = res.liveStatus
        console.log('get live status', liveStatus)
    })
    .catch(err => {
        console.log('get live status', err)
    })
// 往后间隔1分钟或更慢的频率去轮询获取直播状态
setInterval(() => {
    livePlayer.getLiveStatus({ room_id: roomId })
        .then(res => {
            // 101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常,107:已过期 
            const liveStatus = res.liveStatus
            console.log('get live status', liveStatus)
        })
        .catch(err => {
            console.log('get live status', err)
        })
}, 60000)

# 4. 【获取用户 openid 参数】接口(注:若要使用该接口,需在主包/分包先引入直播组件)

接口说明:在直播组件版本 1.3.0 及以上版本通过该接口获取用户 openid 参数。

调用方法:若要调用【获取用户 openid 参数】接口 getOpenid,需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下:

let livePlayer = requirePlugin('live-player-plugin')

App({
    onShow(options) {
        livePlayer.getOpenid({ room_id: [直播房间id] }) // 该接口传入参数为房间号
            .then(res => {
                console.log('get openid', res.openid) // 用户openid
            }).catch(err => {
                console.log('get openid', err)
            })
    }
})

# 5. 【获取分享卡片链接参数】接口(注:若要使用该接口,需在主包/分包先引入直播组件)

接口说明:由于基础库数据安全策略,通过 App onShow(需在主包引入直播组件)或者 Page onShow(需在分包引入直播组件)生命周期里的 query 无法获取直播间分享卡片链接参数。在直播组件版本 1.3.0 及以上版本通过该接口获取以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。

  • 分享卡片进入直播间:房间号 room_id + 进入者 openid + 分享者 share_openid + 开发者自定义参数 custom_params

调用方法:若要调用【获取分享卡片链接参数】接口 getShareParams,需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下:

let livePlayer = requirePlugin('live-player-plugin')

App({
    onShow(options) {
        // 分享卡片/订阅消息/扫码二维码/广告/朋友圈等场景才能调用 getShareParams 接口获取以下参数
        const sceneList = [1007, 1008, 1014, 1044, 1045, 1046, 1047, 1048, 1049, 1073, 1154, 1155]
        if (sceneList.includes(options.scene)) {
            livePlayer.getShareParams()
                .then(res => {
                    // 房间号
                    console.log('get room id', res.room_id) 
                    // 用户openid
                    console.log('get openid', res.openid) 
                    // 分享者openid,分享卡片进入场景才有
                    console.log('get share openid', res.share_openid) 
                    // 开发者在跳转进入直播间页面时,页面路径上携带的自定义参数,这里传回给开发者
                    console.log('get custom params', res.custom_params) 
                }).catch(err => {
                    console.log('get share params', err)
                })
        }
    }
})