小程序直播【直播挂件组件】

一、 挂件功能背景

为了减轻商家的开发和配置成本,小程序直播提供了直播挂件组件,让商家可以轻松的把直播挂件(直播间入口)挂在当前小程序页面上,为直播间汇聚分散在小程序其他页面的流量;特别是商品详情页这类有规律的页面,组件会自动匹配相关商品的直播间。

二、挂件功能说明

功能解释:直播间挂件状态系统默认的优先级是:直播中 > 预告 > 精彩片段 > 回放,也可以单独声明只取部分状态,同状态下离当前时间最近的直播间优先。开了官方收录的直播间才会被选取,可避免选取到商家测试的直播间。

注意:实现挂件能力需要直播组件更新到 1.3.0 及以上版本。

组件使用:商家只需要引入【直播挂件】组件 pendant,声明如下:

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

可以被挂的小程序页面类型:

1. 单一页面

针对要挂直播挂件的单一页面(如小程序首页),无需指定参数,默认挂最新房间。

可选参数使用说明如下:

  • type:表示显示的直播挂件类型,类型为 Number(默认为 0,可选)
  • customParams:表示自定义参数,类型为 String(默认为空,可选)
  • closePictureInPictureMode:表示关闭小窗开关,类型为 Number(默认为0,可选)
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件;1. 只显示直播的挂件;2. 只显示预告的挂件;3. 只显示商品讲解的挂件;4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
<pendant type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>

2. 有规律同类型页面

针对有规律同类型页面(如小程序商品详情页),需要同时声明页面路径url及商品key列表参数(这里我们会把通过正常商家在直播间配置的商品来索引,把对应这个商品最新的直播间匹配挂到商详页)。

必填及可选参数使用说明如下:

  • url:表示页面路径,类型为 String,必填
  • goodsKey:表示商品key列表,类型为 Array,必填
  • type:表示显示的直播挂件类型,类型为 Number(默认为 0,可选)
  • customParams:表示自定义参数,类型为 String(默认为空,可选)
  • closePictureInPictureMode:表示关闭小窗开关,类型为 Number(默认为0,可选)
let url = 'pages/detail/detail?goods_id=1&pid=1', // 小程序商详页路径
let goodsKey = ['pid', 'sid'] // 商品key列表(支持多个key),需要在添加商品时用我们提供的api接口【详见第4节 挂件api接口】传入商品key列表(如示例的'pid', 'sid')
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件;1. 只显示直播的挂件;2. 只显示预告的挂件;3. 只显示商品讲解的挂件;4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    url, // 必填
    goodsKey, // 必填
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
<pendant url="{{url}}" goods-key="{{goodsKey}}" type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>

3. 指定房间号类型页面

针对要挂指定房间号类型页面,只需要声明房间号参数。

必填及可选参数使用说明如下:

  • roomId:表示直播房间号,类型为 Number,必填
  • type:表示显示的直播挂件类型,类型为 Number(默认为 0,可选)
  • customParams:表示自定义参数,类型为 String(默认为空,可选)
  • closePictureInPictureMode:表示关闭小窗开关,类型为 Number(默认为0,可选)
let roomId = 1, // 直播房间号
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件;1. 只显示直播的挂件;2. 只显示预告的挂件;3. 只显示商品讲解的挂件;4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    roomId, // 必填
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
<pendant room-id="{{roomId}}" type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>

三、挂件样式

目前样式只支持商家定义放在页面上的具体位置,样式和颜色暂不支持修改,如下图:

直播挂件

四、挂件api接口

1. 商品添加并提审新增字段:goodsKey

接口说明:

由于在商详页引用直播挂件时并不需要指定该页面对应的商品ID,而直播挂件搜索直播间展示时需要知道该页面对应的商品,所以引用直播挂件时需要有一种能唯一映射商品的方法。 而商详页都会有唯一的url,因此商家在添加商品时需指定该url才能唯一映射此商品。

goodsKey格式为json数组,其内容是url的参数key,我们将使用此goodsKey对应的url的value来唯一映射此商品,映射方式为:%path%_%value1%_%value2%_... ==> 此页面商品
例如"url":"pages/index/index?pid=111&sid=222","goodsKey": ["pid", "sid"],则%path%_%value1%_%value2%_...pages/index/index_111_222,其中pages/index/index_111_222的唯一性须商家保证。

调用频率

调用额度:500次/一天

请求方法

POST

请求URL

https://api.weixin.qq.com/wxaapi/broadcast/goods/add?access_token=

请求参数示例:json

{    
    "goodsInfo": {              
        "coverImgUrl": "ZuYVNKk9sMP1X4m7FXdcDCKra251KDZTjS502UTV7gwalgLZXcrOhG6oNYX6c7AR",        
        "name":"TIT茶杯",      
        "priceType":1,   
        "price":99.5,
        // "price2": 150.5, priceType为2或3时必填
        "url":"pages/index/index?pid=111&sid=222",
        "goodsKey": ["pid", "sid"]
    }
}

2. 直播挂件设置全局 Key

接口说明

若已设置此全局key,且添加商品时未指定goodsKey字段,则我们会使用此全局key作为该商品的goodsKey。 须注意的是,若全局key已设定,并添加了未指定goodsKey字段的商品之后,再重新设定不一样的全局key则会导致先前的映射失效。 为了避免映射失效,建议全局key只设定一次。

注意:key必须为字符串数组

调用频率

调用额度:500次/一天

请求方法

POST

请求URL

https://api.weixin.qq.com/wxaapi/broadcast/goods/setkey?access_token=

请求参数示例:json

{    
    "goodsKey": ["productId""sid"]
}

返回字段:json

{    
    "errcode": 0
}

3. 直播挂件获取全局 Key

接口说明

查看当前设定的全局key。

调用频率

调用额度:500次/一天

请求方法

GET

请求URL

https://api.weixin.qq.com/wxaapi/broadcast/goods/getkey?access_token=

返回字段:json

{    
    "errcode": 0,
    "vendorGoodsKey": [
        "productId""sid"
    ]
}