# 小程序直播-组件接口

## 订阅组件

> 注：若要使用该组件，需在主包/分包先引入直播组件

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

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

### 示例代码如下：

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

然后便可在 home.wxml 里使用订阅组件，其中直播房间 id 可通过下面 [获取直播房间列表](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getliveinfo.md) 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，不阻止事件冒泡）

```javascript
// 传参
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)
}
```

```html
<subscribe
    room-id="{{roomId}}"
    width="{{width}}"
    height="{{height}}"
    font-size="{{fontSize}}"
    color="{{color}}"
    background-color="{{backgroundColor}}"
    custom-params="{{customParams}}"
    bindsubscribe="onSubscribe">
</subscribe>
```

## 获取单次订阅状态接口

> 注：若要使用该接口，需在主包/分包先引入直播组件

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

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

### 示例代码如下：

```javascript
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)
    })
```

## 获取直播状态

> 注：若要使用该接口，需在主包/分包先引入直播组件

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

### 直播状态说明：

- **101 直播中**：表示主播正常开播，直播正常的状态
- **102 未开始**：表示主播还未开播
- **103 已结束**：表示在直播端点击【结束】按钮正常关闭的直播，或直播异常 15 分钟后系统强制结束的直播
- **104 禁播**：表示因违规受到运营处罚被禁播
- **105 暂停中**：表示在 MP 小程序后台-控制台内操作暂停了直播
- **106 异常**：表示主播离开、切后台、断网等情况，该直播被判定为异常状态，15 分钟内恢复即可回到正常直播中的状态；如果 15 分钟后还未恢复，直播间会被系统强制结束直播
- **107 已过期**：表示直播间一直未开播，且已达到在 MP 小程序后台创建直播间时填写的直播计划结束时间，则该直播被判定为过期不能再开播

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

### 示例代码如下：

```javascript
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)
```

## 获取用户openid参数接口

> 注：若要使用该接口，需在主包/分包先引入直播组件

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

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

### 示例代码如下：

```javascript
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)
            })
    }
})
```

## 获取分享卡片链接参数接口

> 注：若要使用该接口，需在主包/分包先引入直播组件

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

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

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

### 示例代码如下：

```javascript
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)
                })
        }
    }
})
```