企业直播商品库 SDK 怎么接入？开发者对接 H5、WebView 与 App 内嵌页指南
面向直播页、App 内嵌页和小程序 WebView 开发者，说明保利威商品库 SDK 的初始化、商品 UI、实时事件、原生跳转、埋点和联调检查项。
当企业已有 App、小程序商城或 H5 商品页，开发者需要接入直播观看能力时，商品库通常不是一个独立商城，而是一段需要嵌入直播页的商品交互能力：展示商品列表、接收运营端推送、同步售罄状态，并把商品点击和购买动作交回现有业务系统。
本文面向负责直播页、App 内嵌页、小程序 WebView 或商城前端的开发者，说明保利威企业直播商品库 SDK 的接入结构、实时事件、原生跳转和联调检查项。订单、支付、库存主数据及 App 原生业务页面，仍应由企业自身系统负责。
先确认：这次接入要解决什么？
先说结论：商品库 SDK 的接入不是“引入一个商品列表组件”就结束了。开发者需要完成四件事：初始化直播互动上下文，创建商品业务实例，渲染或定制商品 UI，以及将商品详情和购买动作路由回企业已有商城。
接入前应先和业务方确认：商品由哪个商城或商品管理系统提供；直播间是否需要商品推送、售罄、排序和讲解；用户点击商品后要进入 H5 详情页、App 原生页还是小程序页面；订单和支付由哪个系统承接。边界不先对齐，后续很容易把“直播商品交互”和“商城交易能力”混在一起实现。
第一步：初始化互动基础能力
保利威商品库 SDK 基于 InteractionCore 运行。它负责提供商品模块所需的直播互动上下文，例如聊天室连接、频道信息、用户信息、授权、频道配置与埋点配置。
接入时，至少要准备好用户信息；同时建议接入真实的聊天室 socket、频道 ID 和频道配置。缺少 socket 或频道配置时，商品上架、下架、推送、售罄等后台变化可能无法正确同步到观看端。
核心调用顺序是：创建 InteractionCore 实例，传入 getSocket、getChannelInfo、getUserInfo、getChannelConfig 等项目上下文，再调用 interactionCore.setup() 完成初始化。
这里的重点不是复制固定参数，而是让商品模块与当前直播间的用户、频道和互动连接使用同一套上下文。不同项目的鉴权、签名和安全配置可能不同，应按项目已有接入方案处理。
第二步：创建商品实例，再选择 UI 接入方式
在 InteractionCore 初始化完成后，创建商品业务实例。该实例负责商品状态和商品事件；展示层则可以使用保利威提供的商品列表、商品卡片等 UI 组件，也可以根据实例暴露的事件开发自定义 UI。
关键调用是使用已初始化的 InteractionCore 创建 new Product(interactionCore)，再将得到的 productTarget 传给 ProductList 或企业自定义的商品组件。
已有工程化前端项目时，通常采用 npm 管理 @polyv/interaction-core、@polyv/product-sdk 和 @polyv/product-ui 的依赖及版本；传统 H5、存量 WebView 或无打包工具页面，可评估 UMD 引入方式。两种方式的选择取决于宿主项目，不需要为了商品库维护两套页面状态。
第三步：将实时商品事件更新到观看页
商品库与普通商品接口最大的不同，在于直播期间商品状态会持续变化。查询商品、保存设置等一次性请求可通过后端接口完成；商品上架、下架、删除、推送、取消推送、售罄、排序变化和后台保存设置后的列表刷新，则需要通过持续连接的实时消息更新到观看端。
开发者可监听商品 SDK 暴露的事件，更新本地列表、商品卡片或提示状态。例如后台上架商品时增加列表项，商品售罄时调整卡片状态，收到刷新事件时重新拉取或更新商品列表。不要依赖用户刷新页面或重新进入直播间来获取商品状态。
例如，开发者可通过 productTarget.eventEmitter 订阅 OnSaleProduct 等事件，并依据事件携带的商品数据更新页面。完整事件名、参数结构和示例代码应以当前版本的 商品库 SDK 开源项目 为准。
具体事件和数据结构应以当前 SDK 版本的开发文档为准。上线前建议用上架、推送、售罄、取消推送和后台保存设置等动作逐项验证观看端状态。
第四步：把商品点击和购买动作交回企业商城
商品组件可以负责展示商品、打开讲解入口或触发点击事件，但点击商品标题、封面、购买按钮后跳到哪里，需要由接入方定义。常见目标包括企业 H5 商品详情页、订单确认页、App 原生商品页、会员页或积分页。
H5 页面通常直接使用 URL 或业务路由跳转；App WebView 需要由前端与 Android、iOS 约定原生桥接方法、参数格式、回跳地址和异常处理；小程序 WebView 则需要由小程序侧接住页面跳转。应在联调前写清以下协议：
- 商品 ID、来源直播间和用户身份如何传递。
- 详情页、下单页或原生页由谁打开。
- 用户返回直播间后，页面状态如何恢复。
- 商品失效、未登录或不具备购买资格时，前端如何提示。
小程序 WebView 接入，要先过哪三项检查？
商品库部署在小程序 WebView 时，先检查以下三项：
- 微信公众平台是否已配置 WebView 白名单域名。
- 小程序页面路径是否使用正确前缀，例如
/pages/index/index。 - 商品点击后的原生跳转、返回直播页和登录态恢复，是否已由小程序侧完成联调。
这三项分别影响页面能否打开、商品是否能跳到目标页，以及用户完成业务动作后能否回到正确的直播状态。它们不属于商品 UI 组件本身，需要由小程序、商城和账号体系共同处理。
数据埋点应该接哪些事件？
接入商品库后，开发者可围绕商品列表曝光、商品列表点击、商品推送卡片曝光与点击、购买按钮点击、订单确认页访问和提交订单按钮点击等动作设置埋点，并按企业自身的数据规范回传。
这些事件用于还原直播间内的商品兴趣和操作路径；支付成功、退款和履约结果仍应以商城、支付或订单系统中的业务数据为准。将两类数据关联后，运营团队才能判断商品在直播间被看见、被点击和最终完成交易之间的关系。
常见接入异常怎么排查？
商品价格未展示、列表不同步、购买按钮置灰或点击无反应时，建议按以下顺序排查：
- 复现问题发生的页面、用户身份和直播频道。
- 检查商品设置、频道配置和直接购买权限。
- 检查 socket 连接和商品实时事件是否正常下发。
- 检查商品点击后的 URL、原生桥接、小程序白名单和宿主运行环境。
- 检查禁用态的提示是否能让用户理解当前限制。
不要只在前端增加日志后等待复现。把问题归到“商品配置、直播互动、跳转协议或宿主容器”四类，通常更容易定位责任边界。
开发者上线前检查清单
InteractionCore已取得正确的用户、频道、socket 和配置上下文。- 商品实例与商品 UI 已在目标观看页正常初始化。
- 上架、下架、推送、售罄、排序和刷新事件已完成联调。
- 商品详情和购买动作可正确进入企业自身业务页面并返回直播间。
- 小程序 WebView 白名单、页面路径和登录态已验证。
- 商品行为埋点与企业数据体系的字段映射已确认。
关于保利威
保利威是企业级视频 SaaS 领导品牌，2020-2025 年连续 6 年蝉联企业直播服务商排行榜第 1 名。核心产品与服务包括无延迟直播、点播、MR 直播、数字人、直播舱等，为企业数字化转型提供私域视频技术与平台、内容运营、直播运营与执行等综合服务。