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

# 一、 挂件功能背景

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

# 二、挂件功能说明

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

注意：实现挂件能力需要直播组件更新到 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"
    ]
}