# 小程序直播-接入说明

小程序直播是微信官方提供的商家经营工具。通过调用该组件，商家可以在小程序中实现直播互动与商品销售闭环。

按照下面的使用说明接入，在你的小程序中引入直播组件即可实现直播功能。使用过程中如遇到问题，可在[小程序直播社区](https://developers.weixin.qq.com/community/minihome/question/1216387783892418561?mockCommonUse=1)发帖交流。

## 一、使用方法说明

### 1.1 直播组件如何引入

**版本限制**：微信客户端版本 7.0.7 及以上（基础库版本2.9.x及以上支持同层渲染）可以观看直播及使用直播间的功能，低版本刚进入直播间时会提示用户升级微信客户端版本（低版本只能观看直播，无法使用直播间的功能）。

**支持在主包或分包内引入【直播组件】 live-player-plugin 代码包（注：直播组件不计入代码包体积），项目根目录的 app.json 引用，示例代码如下：**

1. 主包引入

    ```json
    "plugins": {
        "live-player-plugin": {
            "version": "1.3.0", // 注意填写该直播组件最新版本号，微信开发者工具调试时可获取最新版本号（复制时请去掉注释）
            "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid，该示例值即为直播组件appid（复制时请去掉注释）
        }
    }
    ```

2. 分包引入

    ```json
    "subpackages": [
        {
            "plugins": {
                "live-player-plugin": {
                    "version": "1.3.0", // 注意该直播组件最新版本号，微信开发者工具调试时可获取最新版本号（复制时请去掉注释）
                    "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid，该示例值即为直播组件appid（复制时请去掉注释）
                }
            }
        }
    ]
    ```

### 1.2 直播组件如何使用

按第1步的方法把组件代码包配置引入后，即可直接通过链接地址跳转到直播组件页面（即为进直播间页面）链接地址需要带上直播房间 id；房间 id 可通过下面 [获取直播房间列表](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getliveinfo.md)  API 获取。

### 示例代码如下：

1. 使用 navigator 组件跳转进入直播间

    index.js

    ```javascript
    let roomId = [直播房间id] // 填写具体的房间号，可通过下面【获取直播房间列表】 API 获取
    let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数（如示例中的path和pid参数），后续可以在分享卡片链接和跳转至商详页时获取，详见【获取自定义参数】、【直播间到商详页面携带参数】章节（上限600个字符，超过部分会被截断）
    this.setData({
        roomId,
        customParams
    })
    ```
    index.wxml

    ```html


    ```

2. 使用 navigateTo 方法跳转进入直播间

    index.js

    ```javascript
    let roomId = [直播房间id] // 填写具体的房间号，可通过下面【获取直播房间列表】 API 获取
    let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数（如示例中的path和pid参数），后续可以在分享卡片链接和跳转至商详页时获取，详见【获取自定义参数】、【直播间到商详页面携带参数】章节（上限600个字符，超过部分会被截断）
    wx.navigateTo({
        url: `plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=${roomId}&custom_params=${customParams}`
    })
    // 其中wx2b03c6e691cd7370是直播组件appid不能修改
    ```

通过该链接可跳转到直播组件页面（当前页面入口仅开放 `live-player-plugin`）。

### 示例效果图如下：

![](https://res8.wxqcloud.qq.com.cn/wxdoc/4a0b7f96-8be1-45aa-85b9-01c416156fa5.png)

## 二、直播组件和接口

### 2.1 组件接口

通过在主包/分包中引入直播组件，开发者可以很方便的实现订阅、获取直播状态、获取用户openid以及获取分享卡片链接参数等功能。

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

### 2.2 服务端接口

直播间管理接口，是小程序直播提供给开发者对直播房间进行批量操作的接口能力。开发者可以创建直播间、获取直播间信息、获取直播间回放以及往直播间导入商品。

| 接口名称 | 请求路径 | 描述 |
| --- | --- | --- |
| [创建直播间](/miniprogram/dev/server/API/livebroadcast/studio-management/api_createroom.md) | /wxaapi/broadcast/room/create | 调用此接口创建直播间，创建成功后将在直播间列表展示 |
| [获取直播间列表和回放](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getliveinfo.md) | /wxa/business/getliveinfo | 该接口用于获取直播间列表及直播间信息 |
| [删除直播间](/miniprogram/dev/server/API/livebroadcast/studio-management/api_deleteroom.md) | /wxaapi/broadcast/room/deleteroom | 该接口用于删除直播间 |
| [导入商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_importgoods.md) | /wxaapi/broadcast/room/addgoods | 该接口用于往指定直播间导入商品 |
| [编辑直播间](/miniprogram/dev/server/API/livebroadcast/studio-management/api_editroom.md) | /wxaapi/broadcast/room/editroom | 该接口用于编辑直播间 |
| [获取直播间推流地址](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getpushurl.md) | /wxaapi/broadcast/room/getpushurl | 该接口用于获取直播间推流地址 |
| [获取直播间分享二维码](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getsharedcode.md) | /wxaapi/broadcast/room/getsharedcode | 该接口用于获取直播间分享二维码 |
| [获取主播副号](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getsubanchor.md) | /wxaapi/broadcast/room/getsubanchor | 该接口用于获取主播副号 |
| [修改主播副号](/miniprogram/dev/server/API/livebroadcast/studio-management/api_modifysubanchor.md) | /wxaapi/broadcast/room/modifysubanchor | 该接口用于修改主播副号 |
| [删除主播副号](/miniprogram/dev/server/API/livebroadcast/studio-management/api_deletesubanchor.md) | /wxaapi/broadcast/room/deletesubanchor | 该接口用于删除主播副号 |
| [添加主播副号](/miniprogram/dev/server/API/livebroadcast/studio-management/api_addsubanchor.md) | /wxaapi/broadcast/room/addsubanchor | 该接口用于点击直播副号 |
| [删除直播间商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_deletedoods.md) | /wxaapi/broadcast/goods/deleteInRoom | 该接口用于删除直播间商品 |
| [推送商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_pushgoods.md) | /wxaapi/broadcast/goods/push | 该接口用于推送商品到直播间 |
| [上下架商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_salegoods.md) | /wxaapi/broadcast/goods/onsale | 该接口用于下架或者上架商品 |
| [直播间商品排序](/miniprogram/dev/server/API/livebroadcast/studio-management/api_sortgoods.md) | /wxaapi/broadcast/goods/sort | 该接口用于直播间商品排序 |
| [修改直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_modifyassistant.md) | /wxaapi/broadcast/room/modifyassistant | 该接口用于修改直播间小助手 |
| [查询直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getassistantlist.md) | /wxaapi/broadcast/room/getassistantlist | 该接口用于查询直播间小助手 |
| [删除直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_removeassistant.md) | /wxaapi/broadcast/room/removeassistant | 该接口用于删除直播间小助手 |
| [添加管理直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_addveassistant.md) | /wxaapi/broadcast/room/addassistant | 该接口用于添加管理直播间小助手 |
| [禁言管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatecomment.md) | /wxaapi/broadcast/room/updatecomment | 该接口用于开启/关闭直播间全局禁言 |
| [官方收录管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatefeedpublic.md) | /wxaapi/broadcast/room/updatefeedpublic | 该接口用于开启/关闭直播间官方收录 |
| [客服功能管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatekf.md) | /wxaapi/broadcast/room/updatekf | 该接口用于开启/关闭客服功能 |
| [回放功能管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatereplay.md) | /wxaapi/broadcast/room/updatereplay | 该接口用于开启/关闭回放功能 |
| [下载商品讲解视频](/miniprogram/dev/server/API/livebroadcast/studio-management/api_downloadgoodsvideo.md) | /wxaapi/broadcast/goods/getVideo | 该接口用于下载商品讲解视频 |

商品管理接口是小程序直播提供给开发者对直播商品进行批量操作的接口能力。开发者可以对商品批量进行添加、提审、删除以及更新等操作。

**接口仅支持对通过接口添加的商品进行操作，开发者在小程序管理后台添加的商品，不支持通过接口操作。**

**开发者必须保存【商品ID】与【审核单ID】，如果丢失，则无法调用其他相关接口。**

| 接口名称 | 请求路径 | 描述 |
| --- | --- | --- |
| [删除直播间商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_deletedoods.md) | /wxaapi/broadcast/goods/deleteInRoom | 该接口用于删除直播间商品 |
| [推送商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_pushgoods.md) | /wxaapi/broadcast/goods/push | 该接口用于推送商品到直播间 |
| [上下架商品](/miniprogram/dev/server/API/livebroadcast/studio-management/api_salegoods.md) | /wxaapi/broadcast/goods/onsale | 该接口用于下架或者上架商品 |
| [直播间商品排序](/miniprogram/dev/server/API/livebroadcast/studio-management/api_sortgoods.md) | /wxaapi/broadcast/goods/sort | 该接口用于直播间商品排序 |
| [修改直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_modifyassistant.md) | /wxaapi/broadcast/room/modifyassistant | 该接口用于修改直播间小助手 |
| [查询直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getassistantlist.md) | /wxaapi/broadcast/room/getassistantlist | 该接口用于查询直播间小助手 |
| [删除直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_removeassistant.md) | /wxaapi/broadcast/room/removeassistant | 该接口用于删除直播间小助手 |
| [添加管理直播间小助手](/miniprogram/dev/server/API/livebroadcast/studio-management/api_addveassistant.md) | /wxaapi/broadcast/room/addassistant | 该接口用于添加管理直播间小助手 |
| [禁言管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatecomment.md) | /wxaapi/broadcast/room/updatecomment | 该接口用于开启/关闭直播间全局禁言 |
| [官方收录管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatefeedpublic.md) | /wxaapi/broadcast/room/updatefeedpublic | 该接口用于开启/关闭直播间官方收录 |
| [客服功能管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatekf.md) | /wxaapi/broadcast/room/updatekf | 该接口用于开启/关闭客服功能 |
| [回放功能管理](/miniprogram/dev/server/API/livebroadcast/studio-management/api_updatereplay.md) | /wxaapi/broadcast/room/updatereplay | 该接口用于开启/关闭回放功能 |
| [下载商品讲解视频](/miniprogram/dev/server/API/livebroadcast/studio-management/api_downloadgoodsvideo.md) | /wxaapi/broadcast/goods/getVideo | 该接口用于下载商品讲解视频 |

直播成员管理接口，是小程序直播提供给开发者对直播成员进行批量管理的接口能力。

开发者可以通过接口设置、查询、移除直播成员的角色，不同角色拥有不同的管理权限，具体请查看[小程序直播成员管理说明](https://docs.qq.com/doc/DZFJYVWtZVlpTenlM?_t=1602211045019)。

| 接口名称 | 请求路径 | 描述 |
| --- | --- | --- |
| [设置成员角色](/miniprogram/dev/server/API/livebroadcast/role-management/api_getrolelistdw.md) | /wxaapi/broadcast/role/addrole | 调用此接口设置小程序直播成员的管理员、运营者和主播角色 |
| [移除成员角色](/miniprogram/dev/server/API/livebroadcast/role-management/api_deleterole.md) | /wxaapi/broadcast/role/deleterole | 调用此接口可移除小程序直播成员的管理员、运营者和主播角色 |
| [查询成员列表](/miniprogram/dev/server/API/livebroadcast/role-management/api_getrolelist.md) | /wxaapi/broadcast/role/getrolelist | 该接口用于查询小程序直播成员列表 |

长期订阅接口

| 接口名称 | 请求路径 | 描述 |
| --- | --- | --- |
| [发送直播开始事件](/miniprogram/dev/server/API/livebroadcast/subscribe-management/api_pushmessage.md) | /wxa/business/push_message | 该接口用于向长期订阅用户群发直播间开始事件 |
| [获取长期订阅用户](/miniprogram/dev/server/API/livebroadcast/subscribe-management/api_getfollowers.md) | /wxa/business/get_wxa_followers | 该接口用于获取长期订阅用户列表 |
| [长期订阅状态同步接口](/miniprogram/dev/server/event_push/liveplayer/status_synchronization.md)| 事件通知 | |
| [长期订阅群发结果通知](/miniprogram/dev/server/event_push/liveplayer/longterm_subscription.md)| 事件通知 | |