小程序直播開發

小程序直播

一、 簡介

小程序直播是微信官方提供的商家經營工具。通過調用該組件，商家可以在小程序中實現直播互動與商品銷售閉環。

按照下面的使用說明接入，在你的小程序中引入直播組件即可實現直播功能。使用過程中如遇到問題，可在小程序直播社區發帖交流。

二、 使用方法說明

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. 修復進直播間閃現貨架問題