Browser SDK 参考
本文是 Browser SDK（window.sdk）的参考手册：如何从页面发起 PWA 安装提示、订阅访客推送通知、发送事件，以及所需的配置项。如需整体介绍，请参阅 Browser SDK；如需将其接入自己的预落地页，请参阅 在预落地页上使用 SDK。
window.pwaConfig 配置项
SDK 从 window.pwaConfig 对象中读取配置，该对象需在页面的 script 标签之前设置。在 Qubix 托管的页面上，该对象会自动填充；在您自己的预落地页上，需手动设置。
| 字段 | 用途 |
|---|---|
pwaId | PWA 标识符。安装和推送均需此字段 |
domain | 页面的域名。manifest 和推送均需此字段 |
vapidKey | 推送所用的密钥。通常在 /sdk.js 加载时自动内联——无需手动设置 |
offerId | Offer（如需显式传入） |
campaignId | 活动（如需显式传入） |
params | 额外的追踪标签 |
previewMode | 预览模式：事件不会被发送 |
PWA 标识符（pwaId）可在 PWA 应用 板块的应用卡片中获取。
订阅推送
sdk.subscribePush() 向浏览器请求通知权限并创建订阅。您必须显式调用它——例如，在按钮点击时触发。它不会自动执行。
const subscription = await sdk.subscribePush()
if (subscription) {
// 访客已允许通知并完成订阅
}
内部流程：
- 显示浏览器的权限请求提示。
- 若访客允许，则创建订阅并发送至 Qubix。
- 重复调用是安全的：若访客已订阅，则不再显示提示。
推送不要求安装 App——访客可以在普通页面上完成订阅。
推送仅在安全连接（HTTPS）且域名已在 Qubix 中配置的情况下有效。详情请参阅 在预落地页上使用 SDK。
安装 PWA
若 window.pwaConfig 中设置了 pwaId，SDK 会暴露 sdk.pwa 方法：
| 方法 | 作用 |
|---|---|
sdk.pwa.init() | 准备工作：注册 service worker 并附加 App manifest |
sdk.pwa.install() | 显示系统的 App 安装提示 |
sdk.pwa.canInstall() | 当前是否可以安装 |
sdk.pwa.isInstalled() | App 是否已安装 |
sdk.pwa.open() | 打开已安装的 App |
init、install 和 isInstalled 是异步的——请用 await 调用。canInstall 和 open 立即返回结果。
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
安装提示由浏览器本身显示，因此需遵循其规则：HTTPS、已附加 manifest（SDK 会自动附加）以及通常需要访客在页面上有操作（点击、滚动）。这也是安装按钮通常绑定到明确点击的原因。
事件
SDK 会自动向数据分析报告关键时刻——可在报告和事件流中查看：
| 事件 | 触发时机 |
|---|---|
campaign_visit | 访客访问页面（自动发送） |
push_prompt_shown | 显示了推送权限请求提示 |
push_allow | 访客允许了推送 |
push_deny | 访客拒绝了推送 |
push_ignored | 访客未做选择地关闭了提示 |
install_accepted | 访客同意安装 App |
install_rejected | 访客拒绝安装 |
您也可以手动发送自定义事件：
sdk.sendEvent('my_button_click', { place: 'hero' })
流量数据
用于读取点击上下文的辅助方法：
| 方法 | 返回内容 |
|---|---|
sdk.getOffer() | 当前 offer（ID 和 URL） |
sdk.getPwa() | 当前 PWA |
sdk.getPiuid() | 访客 ID |
sdk.getTrackingParams() | 随点击传入的追踪标签 |
sdk.buildOfferUrl(url) | 构建带追踪标签的 offer URL |
sdk.showStore() | 跳转到 PWA 商店卡片 |
SDK 自动执行的操作
无需任何代码调用，SDK 在页面加载时会自动：收集设备数据、解析 URL 中的追踪标签、附加 App manifest（若设置了 pwaId）并发送 campaign_visit 事件。安装和推送订阅不会自动触发——需通过代码显式调用。