小程序直播是微信官方提供的商家经营工具。通过调用该组件,商家可以在小程序中实现直播互动与商品销售闭环。
按照下面的使用说明接入,在你的小程序中引入直播组件即可实现直播功能。使用过程中如遇到问题,可在小程序直播社区发帖交流。
版本限制:微信客户端版本 7.0.7 及以上(基础库版本2.9.x及以上支持同层渲染)可以观看直播及使用直播间的功能,低版本刚进入直播间时会提示用户升级微信客户端版本(低版本只能观看直播,无法使用直播间的功能)。
"plugins": { "live-player-plugin": { "version": "1.0.9", // 注意填写该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释) "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释) } }
"subpackages": [ { "plugins": { "live-player-plugin": { "version": "1.0.9", // 注意该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释) "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释) } } } ]
按第1步的方法把组件代码包配置引入后,即可直接通过链接地址跳转到直播组件页面(即为进直播间页面)链接地址需要带上直播房间 id;房间 id 可通过下面【获取直播房间列表】 API 获取。
let roomId = [直播房间id] // 填写具体的房间号,可通过下面【获取直播房间列表】 API 获取 let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断) this.setData({ roomId, customParams })
<navigator url="plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id={{roomId}}&custom_params={{customParams}}"></navigator> // 其中wx2b03c6e691cd7370是直播组件appid不能修改
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
功能解释:用户进入直播间内,可对一场未开播的直播进行单次订阅,开播时直播组件会自动下发开播提醒给用户,无需开发者额外开发
组件使用:如果需要在直播组件页以外小程序其他页面也有同样的开播提醒的功能,可以引入【订阅】组件 subscribe(开播前才会显示,直播开始后自动消失该组件);需在 page 页面(如 home 页面)的 home.json 引用订阅组件。
{ "usingComponents": { "subscribe": "plugin-private://wx2b03c6e691cd7370/components/subscribe/subscribe" } }
然后便可在 home.wxml 里使用订阅组件,其中直播房间 id 可通过;房间 id 可通过下面【获取直播房间列表】 API 获取
<subscribe room-id="[直播房间id]"></subscribe>
接口说明:首次获取立马返回直播状态,往后间隔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)
接口说明:在直播组件版本 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) }) } })
接口说明:由于基础库数据安全策略,通过App onShow 生命周期里的query无法获取直播间分享卡片链接参数。在直播组件版本 1.0.9 及以上版本通过该接口获取以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。
调用方法:若要调用【获取分享卡片链接参数】接口 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) }) } } })
版本限制:直播组件版本 1.0.9 及以上支持携带以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。
(1) shareTicket:分享直播间卡片到微信群,点击此卡片后可以在 App onShow 里获取该参数(默认可获取该参数,但长按分享卡片时不能转发。可在跳转直播间页面路径上配置close_share_ticket=1关闭shareTicket,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&close_share_ticket=1",此时长按分享卡片时可以转发。)
(2) room_id + openid + share_openid + custom_params :点击直播间里的货架商品跳转到商家小程序的商品详情页或点击直播间左上角首页icon跳转到商家小程序的首页时,可以在Page onLoad options里获取房间号、用户openid、分享者share_openid(如果是从分享卡片进入直播间再跳转到商详页才有该参数)、开发者携带的自定义参数custom_params
版本限制:直播组件版本 1.0.9 及以上支持通过以下参数设置是否关闭小窗。
close_picture_in_picture_mode:默认支持直播小窗,可通过close_picture_in_picture_mode=1关闭小窗功能,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&close_picture_in_picture_mode=1"。
接口规则:该接口仅供商家后台调用,调用限额 10 万次/天,200 次/分钟,建议开发者自己做缓存(此接口与下面【获取回放视频】接口共用 10 万次/天限制,200 次/分钟,请合理分配调用频次)。
请求URL: http://api.weixin.qq.com/wxa/business/getliveinfo?access_token=
请求方式: POST
{ "start": 0, // 起始拉取房间,start = 0 表示从第 1 个房间开始拉取 "limit": 10 // 每次拉取的个数上限,不要设置过大,建议 100 以内 }
{ "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", "share_img": "http:\/\/mmbiz.qpic.cn\/mmbiz_jpg\/Rl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ\/0?wx_fmt=jpeg", "live_status": 101, "start_time": 1568128900, "end_time": 1568131200, "anchor_name": "李四", "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
cover_img 直播间背景墙
share_img 分享卡片封面
start_time 直播计划开始时间,列表按照 start_time 降序排列
end_time 直播计划结束时间
anchor_name 主播名
goods 商品列表
live_status 直播状态 101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常, 107: 已过期(直播状态解释可参考【获取直播状态】接口)
接口规则:该接口仅供商家后台调用,调用限额 10 万次/天,200 次/分钟,此接口与上面【获取房间列表】接口共用 10 万次/天限制,200 次/分钟,请合理分配调用频次)。
该接口可在直播结束后拿到回放源视频(直播结束后大约 10 分钟会生成回放,源视频无评论等内容)
拿到源视频后需要开发者自行开发、使用回放视频
如果把源视频直接放在小程序上使用,需要小程序具备视频资质(具体资质要求请参考《小程序开发的类目服务》)
官方已提供了回放功能(直播组件版本1.0.9及以上版本)无需开发,官方提供的回放视频有效期为1年,如需长期保持可用上面接口获取下载保存。
请求URL: http://api.weixin.qq.com/wxa/business/getliveinfo?access_token=
请求方式: POST
{ "action": "get_replay", // 获取回放 "room_id": 354, // 直播间 id "start": 0, // 起始拉取视频,start = 0 表示从第 1 个视频片段开始拉取 "limit": 10 // 每次拉取的个数上限,不要设置过大,建议 100 以内 }
{ "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 万次/天。
请求URL: https://api.weixin.qq.com/wxaapi/broadcast/room/create?access_token=
请求方式: POST
{ "name" : "测试直播间" //房间名字 "coverImg": "xxxxxx" //填写mediaID,直播间背景图,图片规则:建议像素800*640,大小不超过1M,mediaID获取参考:https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html) "startTime": 1588237130 // 直播计划开始时间,1.开播时间需在当前时间10min后,2.开始时间不能在6个月后 "endTime": 1588237130 //直播计划结束时间,1.开播时间和结束时间间隔不得短于30min,不得超过24小时 "anchorName": "test1" // 主播昵称 "anchorWechat":"test1" //主播微信号,需通过实名认证,否则将报错 "anchorImg":"xxx" //填写mediaID,直播间分享图,图片规则:建议像素1080*1920,大小不超过2M,mediaID获取参考:https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html) "type":1 //直播类型,1:推流,0:手机直播 "screenType":0 //1:横屏,0:竖屏,自动根据实际视频分辨率调整 "closeLike":0 //1:关闭点赞 0:开启点赞 ,关闭后无法开启 "closeGoods":0 //1:关闭货架 0:打开货架,关闭后无法开启 "closeComment":0 //1:关闭评论 0:打开评论,关闭后无法开启 }
{ "roomId": 33, //房间ID "errcode": 0 }
小程序引入直播组件后必须进行一次小程序发布上线,否则直播间的小程序码不生效,具体表现是用户扫码进入直播间会显示“页面不存在”。
在 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))"。
商家在公众号文章中添加跳转进入直播间的小程序卡片时,需要做以下配置: 在跳转进入直播间的路径加上 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))"。
(1)添加返回按钮: 点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面后,为了避免用户无法再返回直播间,商家需在小程序商品详情页面左上角加上返回按钮,通过wx.navigateBack返回到直播组件页面。(2)不建议使用wx.switchTab:若在商品详情页点击按钮(如购物车按钮等)通过wx.switchTab跳转到tabbar页,然后再点小窗回到直播间时会出现页面卡死问题(微信客户端7.0.15版本才修复)。此时可把页面改为非tabbar页并通过wx.navigateTo跳转,也可通过关闭小窗来解决该问题。 (3)不建议使用wx.reLaunch:若在商品详情页及之后的页面元素上使用wx.reLaunch跳转,不仅会关闭小窗,而且无法返回到上一页,体验不好。
商家小程序对应的管理员微信号收到【公众平台安全助手】下发的直播组件版本更新的服务通知后,可点击通知进行快速发布,移动端即可快速更新小程序内直播组件的新版本,无需修改代码或重新提交审核。