小程序直播开发

小程序直播

一、 简介

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

按照下面的使用说明接入，在你的小程序中引入直播组件即可实现直播功能。使用过程中如遇到问题，可在小程序直播社区发帖交流。

二、 使用方法说明

1. 【直播组件】如何引入

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

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

1. 主包引入

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

2. 分包引入

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

2. 【直播组件】如何使用

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

示例代码如下：

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

index.js

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

index.wxml

    <navigator url="plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id={{roomId}}&custom_params={{customParams}}"></navigator>
    // 其中wx2b03c6e691cd7370是直播组件appid不能修改

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

index.js

    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’）。

示例效果图如下：

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

• 订阅组件： subscribe

• 获取直播状态API： getLiveStatus

• 获取用户openid参数API： getOpenid

• 获取分享卡片链接参数API： getShareParams

• 直播间到商详页面携带参数：room_id + openid + share_openid + custom_params

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

• 直播小窗控制参数： close_picture_in_picture_mode

• 后台获取直播房间列表 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分钟或更慢的频率去轮询获取直播状态

直播状态说明：

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

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

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

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

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

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

• 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
            console.log('get live status', liveStatus)
        })
        .catch(err => {
            console.log('get live status', err)
        })

3. 【获取用户openid参数】接口（注：若要使用该接口，需在主包引入直播组件）

接口说明：在直播组件版本 1.0.9 及以上版本通过该接口获取用户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)
                })
        }
    })

4. 【获取分享卡片链接参数】接口（注：若要使用该接口，需在主包引入直播组件）

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

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

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

示例代码如下：

    let livePlayer = requirePlugin('live-player-plugin')
    
    App({
        onShow(options) {
            // 分享卡片入口场景才调用getShareParams接口获取以下参数
            if (options.scene == 1007 || options.scene == 1008 || options.scene == 1044) {
                livePlayer.getShareParams()
                    .then(res => {
                        console.log('get room id', res.room_id) // 房间号
                        console.log('get openid', res.openid) // 用户openid
                        console.log('get share openid', res.share_openid) // 分享者openid，分享卡片进入场景才有
                        console.log('get custom params', res.custom_params) // 开发者在跳转进入直播间页面时，页面路径上携带的自定义参数，这里传回给开发者
                    }).catch(err => {
                        console.log('get share params', err)
                    })
            }
        }
    })

5. 携带参数

版本限制：直播组件版本 1.0.9 及以上支持携带以下参数，开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。

（1） shareTicket：分享直播间卡片到微信群，点击此卡片后可以在 App onShow 里获取该参数（默认可获取该参数，但长按分享卡片时不能转发。可通过close_share_ticket=1关闭shareTicket，此时长按分享卡片时可以转发。）

（2） room_id + openid + share_openid + custom_params ：点击直播间里的货架商品跳转到商家小程序的商品详情页或点击直播间左上角首页icon跳转到商家小程序的首页时，可以在Page onLoad options里获取房间号、用户openid、分享者share_openid（如果是从分享卡片进入直播间再跳转到商详页才有该参数）、开发者携带的自定义参数custom_params

6. 直播小窗

版本限制：直播组件版本 1.0.9 及以上支持通过以下参数设置是否关闭小窗。

close_picture_in_picture_mode：默认支持直播小窗，可通过close_picture_in_picture_mode=1关闭小窗功能。

7. 【获取直播房间列表】接口，仅供后台调用

接口规则：该接口仅供商家后台调用，调用限额 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_status": 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 直播间背景墙

• start_time 直播计划开始时间，列表按照 start_time 降序排列

• end_time 直播计划结束时间

• anchor_name 主播名

• goods 商品列表

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

8. 【获取回放源视频】接口，仅供后台调用

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

接口说明：

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

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

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

官方已提供了回放功能（直播组件版本1.0.9及以上版本）无需开发，官方提供的回放视频有效期为1年，如需长期保持可用上面接口获取下载保存。

请求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"。 若需要带上自定义参数则还需要加上 custom_params： "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=9&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

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

说明：

商家在公众号文章中添加跳转进入直播间的小程序卡片时，需要做以下配置： 在跳转进入直播间的路径加上 type = 10 标识场景入口为小程序卡片： "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10"。 若需要带上自定义参数则还需要加上 custom_params： "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

3、 商品详情页注意事项

（1）添加返回按钮: 点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面后，为了避免用户无法再返回直播间，商家需在小程序商品详情页面左上角加上返回按钮，通过wx.navigateBack返回到直播组件页面。 （2）不建议使用wx.switchTab：若在商品详情页点击按钮（如购物车按钮等）通过wx.switchTab跳转到tabbar页，然后再点小窗回到直播间时会出现页面卡死问题（微信客户端7.0.15版本才修复）。此时可把页面改为非tabbar页并通过wx.navigateTo跳转，也可通过关闭小窗来解决该问题。 （3）不建议使用wx.reLaunch：若在商品详情页及之后的页面元素上使用wx.reLaunch跳转，不仅会关闭小窗，而且无法返回到上一页，体验不好。

4、 快速更新直播组件版本的方法

商家小程序对应的管理员微信号收到【公众平台安全助手】下发的直播组件版本更新的服务通知后，可点击通知进行快速发布，移动端即可快速更新小程序内直播组件的新版本，无需修改代码或重新提交审核。

服务通知如下图所示：

五、 版本更新日志

1.0.0

1. 新增直播小窗效果
2. 分享入口外显直播间
3. 直播结束页商品展示优化
4. 抽奖地址优化

1.0.1

1. 缩减代码包体积至 445 KB
2. 跳转至商品详情页时带上 room_id 参数
3. 分享时带上 shareTicket 参数给商家
4. 获取直播状态接口优化

1.0.2

1. 携带 openid / room_id / 自定义参数给开发者
2. 优化跳转至商详页再跳回直播间先load封面问题
3. 修复 windows 平台无法观看直播问题
4. 修复企业微信提示升级问题

1.0.3

1. 新增推流功能
2. 获取分享链接参数getShareParams接口优化

1.0.4

1. 新增回放功能
2. 通过close_share_ticket参数设置shareTicket
3. 商品链接支持跳转到tab页面

1.0.5

1. 优化部分机型回放拉伸等问题
2. 修复直播小窗重音问题
3. 修复客户端导致点赞动画显示问题
4. 修复跳转其他页面提示“当前处于非WiFi环境，请注意流量消耗”问题

1.0.6

1. 新增小助手功能

1.0.8

1. 新增竖屏清屏功能
2. 新增回放视频小窗功能
3. 优化评论区域卡顿问题
4. 修复商品链接type参数被覆盖问题
5. 修复商品链接参数里的html被去掉问题

1.0.9

1. 修复进直播间闪现货架问题