小程序直播组件接入指引

╰+哭是因爲堅強的太久メ 2021-07-24 16:27 588阅读 0赞

**已订阅**

###    一、简介 ###

小程序直播，是微信提供给小程序开发者的直播组件。通过调用该组件，商家可以在小程序中实现直播功能。

按下面的使用说明接入，在你的小程序中引入直播组件。

### 二、使用方法说明 ###

**1.  【直播组件】如何引入  
版本限制：**

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

在分包内引入【直播组件】live-player-plugin代码包，项目根目录的 app.json 引用，示例代码如下：

{
     
      "subpackages": [
     
        {
     
          "root": "packageA",
     
          "pages": [
     
            "pages/home/home"
     
          ],
     
          "plugins": {
     
            "live-player-plugin": {         
     
    "version": "1.0.0", // 填写该直播组件最新版本号，微信开发者工具调试时可获取最新版本号
     
              "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid，该示例值即为直播组件appid
     
            }
     
          }
     
        }
     
      ]
     
    }

**2.   【直播组件】如何使用**  
按第1步的方法把组件代码包配置引入后，即可直接通过链接地址跳转到直播组件页面（即为进直播间页面）链接地址需要带上直播房间id；房间id可通过下面【获取直播房间列表】API获取，示例代码如下：

<navigator url="plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]">
     
      Go to Live Player page
     
    </navigator>

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

示例效果图如下：

### 三、其他相关组件、接口和携带参数 ###

●    订阅组件：subscribe

●    获取直播状态API：getLiveStatus

●    直播间到商详页面携带参数：room\_id

●    从群分享卡片返回直播间时携带参数：shareTicket

●    后台获取直播房间列表API

●    后台获取回放源视频API

注：以上2个后台调用的接口总上限500次/天

**1.   【订阅】组件**  
功能解释：

用户进入直播间内，可对一场未开播的直播进行单次订阅，开播时直播组件会自动下发开播提醒给用户，无需开发者额外开发

组件使用：

如果需要在直播组件页以外小程序其他页面也有同样的开播提醒的功能，可以引入【订阅】组件subscribe；需在page页面（如home页面）的 home.json 引用订阅组件，示例代码如下：

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

然后便可在home.wxml里使用订阅组件，其中直播房间id可通过；房间id可通过下面【获取直播房间列表】API获取

<subscribe room-id="\[直播房间id\]"></subscribe>  
**2.   【获取直播状态】接口**  
接口说明：

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

直播状态说明：

l  101直播中：表示主播正常开播，直播正常的状态；

l  102未开始：表示主播还未开播；

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

l  104禁播：表示因违规受到运营处罚被禁播；

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

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

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

调用方法：

若要调用【获取直播状态】接口getLiveStatus，需在小程序页面顶部引用【直播组件】live-player-plugin，示例代码如下：

let livePlayer = requirePlugin('live-player-plugin') // 引入获取直播状态接口

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

const roomId = xxx  
   
// 房间id  
   
livePlayer.getLiveStatus(\{ room\_id: roomId \})  
   
  .then(res => \{  
   
    //  
   
101: 直播中, 102: 未开始, 103: 已结束,  
   
104: 禁播, 105: 暂停中, 106: 异常，107：已过期  
   
    const  
   
liveStatus = res.liveStatus  
   
  \})  
   
  .catch(err =>  
   
\{  
   
    console.log(err)  
   
  \})  
**3.   携带参数**  
版本限制：

直播组件版本1.0.1及以上支持携带以下参数

shareTicket：分享直播间卡片到微信群，点击此卡片后可以在 ApponShow 里获取该参数

room\_id：点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面时，会带上房间号参数

**4.   【获取直播房间列表】接口，仅供后台调用**  
接口规则：

该接口仅供商家后台调用，调用限额500次/天，建议开发者自己做缓存（此接口与下面【获取回放视频】接口共用500次/天限制，请合理分配调用频次）。

请求URL：

http://api.weixin.qq.com/wxa/business/getliveinfo?access\_token=

请求方式：

POST

请求示例：

Request
     
    {
     
     "start": 0, // 起始拉取房间，start=0表示从第1个房间开始拉取
     
     "limit": 10 // 每次拉取的个数上限，不要设置过大，建议100以内
     
    }
     
     
     
    Response
     
    {
     
     "errcode": 0, // errcode=0代表成功；errcode=1代表未创建直播房间
     
     "errmsg": "ok",
     
     "room_info": [{
     
    "name": "直播房间名", 
     
    "roomid": 1,
     
    "cover_img": "http:\/\/mmbiz.qpic.cn\/mmbiz_jpg\/Rl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ\/0?wx_fmt=jpeg", 
     
    "live_satus": 101,
     
    "start_time": 1568128900,
     
    "end_time": 1568131200,
     
    "anchor_name": "李四",
     
    "anchor_img": "http:\/\/mmbiz.qpic.cn\/mmbiz_jpg\/Rl1RuuhdstSfZa8EEljedAYcbtX3Ejpdlp0sf9YTorOzUbGF9Eib6ic54k9fX0xreAIt35HCeiakO04yCwymoKTjw\/0?wx_fmt=jpeg",
     
    "goods":[            
     
    {    "cover_img":"http://mmbiz.qpic.cn/mmbiz_png/FVribAGdErI2PmyST9ZM0JLbNM48I7TH2FlrwYOlnYqGaej8qKubG1EvK0QIkkwqvicrYTzVtjKmSZSeY5ianc3mw/0?wx_fmt=png",
     
          "url":"pages/index/index.html",
     
          "price":1100,
     
          "name":"fdgfgf"   
     
    }  
     
    ],
     
     "total":1
     
    }

返回字段：

name 房间名

roomid 房间id

注：需先在小程序MP后台创建直播房间，否则会报错（错误码1）

cover\_img 封面图片url

start\_time 直播计划开始时间，列表按照 start\_time 降序排列

end\_time 直播计划结束时间

anchor\_name 主播名

goods 商品列表

live\_status 直播状态   101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常,107:已过期（直播状态解释可参考【获取直播状态】接口）

**5.   【获取回放源视频】接口，仅供后台调用**  
接口规则：

该接口仅供商家后台调用，调用限额500次/天，此接口与上面【获取房间列表】接口共用500次/天限制，请合理分配调用频次）。

接口说明：

该接口可在直播结束后拿到回放源视频（直播结束后大约10分钟会生成回放，源视频无评论等内容）

拿到源视频后需要开发者自行开发、使用回放视频

如果把源视频直接放在小程序上使用，需要小程序具备视频资质（具体资质要求请参考《小程序开发的类目服务》）

后续官方会直接提供无需开发的直播回放功能，敬请期待。

请求URL：

http://api.weixin.qq.com/wxa/business/getliveinfo?access\_token=

请求方式：

POST

请求示例：

Request
     
    {
     
    "action": "get_replay", // 获取回放
     
    "room_id": 354, // 直播间id
     
    "start": 0, // 起始拉取视频，start=0表示从第1个视频片段开始拉取
     
    "limit": 10 // 每次拉取的个数上限，不要设置过大，建议100以内
     
    }
     
     
     
    Response
     
    {
     
    "live_replay": [  
     
    {
     
          "expire_time": "2020-11-11T03:49:55Z", // 回放视频url过期时间
     
          "create_time": "2019-11-12T03:49:55Z", // 回放视频创建时间
     
          "media_url": "http://xxxxx.vod2.myqcloud.com/xxxxx/xxxxx/f0.mp4" // 回放视频   
     
    } 
     
    ], 
     
    "errcode": 0, 
     
    "total": 1, 
     
    "errmsg": "ok"
     
    } // 一场直播可能会产生多个视频片段。

###    四、其他说明 ###

**1、直播间小程序码**  
说明：

小程序引入直播组件后必须进行一次小程序发布上线，否则小程序码不生效

在MP小程序直播后台创建好直播间后，可以直接拿到直播间分享小程序码，无需额外开发

如果商家在后台自己生成的直播间小程序码，需要做以下配置（否则直播间左上角返回键将失效）：

在跳转进入直播间的路径加上 type=9 标识场景入口为小程序码：

"plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room\_id=\[直播房间id\]&type=9"

**2、商家公众号文章添加小程序卡片**  
说明：

商家在公众号文章中添加跳转进入直播间的小程序卡片时，需要做以下配置（否则直播间左上角返回键将失效）：

在跳转进入直播间的路径加上 type=10 标识场景入口为小程序卡片：

"plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room\_id=\[直播房间id\]&type=10"

**3、商品详情页面需添加返回按钮**  
点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面后，为了避免用户无法再返回直播间，商家需在小程序商品详情页面左上角加上返回按钮，用于返回到直播组件页面。