订阅小组件

订阅小组件由一个提示和一个启动器铃铛组成，邀请网站访问者订阅推送通知。二者通过 subscriptionWidget 一并配置，但可独立启用：只启用提示、只启用铃铛，或两者同时启用。启用其中任何一个，都会取代推送订阅按钮、自定义订阅弹窗和订阅提示——只要至少有一部分处于启用状态，这三个旧版小组件都不会加载到页面上。

尚未做出决定的访问者会看到提示中的请求。已经屏蔽通知的访问者则会看到关于如何解除屏蔽的说明。

前提条件

请确保您已在网站上实现了 Pushwoosh Web SDK 3.0。为此，请遵循我们的集成指南。

1. 启用提示和铃铛

在 WebSDK 初始化时添加 subscriptionWidget 参数，并将 prompt.enabled 和/或 launcher.enabled 设置为 true：

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

没有单一的顶层开关

顶层的 subscriptionWidget.enable 不会被读取。只设置该字段不会启用任何内容。请参阅下文的从旧版小组件迁移。

以下每个字段都是可选的。省略的字段将回退到其默认值。在 init 代码段中，超出范围的数字会被静默地限制到最近的边界值，无效的枚举值也会静默地回退到其默认值，且不会有控制台警告。下文所述的 Control Panel 表单会校验每个字段，并拒绝保存无效值。

2. 配置提示和铃铛

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

布局与位置

prompt.layout 设置提示的形状：

• card —— 锚定在边缘或角落的紧凑卡片。prompt.position 接受 top、bottom、top-left、top-right、bottom-left 或 bottom-right。
• bar —— 横跨页面全宽的横幅。prompt.position 仅接受 top 或 bottom。
• modal —— 在页面中央显示的窗口。prompt.position 始终为 center。

在选择位置之前，请先查看上方列表以确认您设置的布局。在 init 代码段中，当前布局不支持的位置会被静默替换为该布局的默认值。Control Panel 表单则会直接拒绝这种组合。

何时展示提示

display.trigger 控制什么会打开提示：

• auto —— 页面加载后 display.delay 秒自动打开，此后如果访问者尚未做出决定，则每隔 display.cappingInterval 小时再次打开，总共最多 display.cappingCount 次（0 表示无限制）。
• launcher —— 从不按计时器打开。请与 launcher.enabled: true 搭配设置，以便点击铃铛来打开它。无论此设置如何，也无论铃铛是否启用，手动 API 仍可打开它。
• manual —— 仅通过下文所述的 Pushwoosh.moduleRegistry.subscriptionWidget 打开。

display.delay、display.cappingCount 和 display.cappingInterval 仅适用于 auto 触发方式。

启动器铃铛

launcher.enabled 会向仍可对该请求采取行动的访问者（尚未订阅或已屏蔽）显示一个悬浮铃铛，与提示及 display.trigger 无关。提示打开时，铃铛仍会保持在屏幕上。launcher.position 将其放置在四个角落之一。launcher.offset 设置其距边缘的像素距离。

点击铃铛的效果取决于提示。如果 prompt.enabled 为 true，点击会切换提示：打开它，或在已打开时关闭它。如果提示未启用，点击会直接向浏览器请求权限，与 Pushwoosh.subscribe() 相同——除非访问者已屏蔽通知，此时点击不会有任何效果。

launcher.width 和 launcher.height 以像素为单位设置铃铛的大小（16–200，默认均为 48）。launcher.imageUrl 会绘制一张图片，以取代圆形铃铛按钮。launcher.background 和 launcher.iconColor 设置圆形按钮的填充色和图标颜色。未设置时，launcher.background 默认为调色板的强调色，launcher.iconColor 默认为根据对比度计算出的图标颜色。

文本与颜色

一旦浏览器报告访问者已屏蔽通知，texts.blockedTitle、texts.blockedMessage 和 texts.closeText 就会取代请求文本显示——此状态下 texts.acceptText 和 texts.declineText 永远不会出现。texts.launcherLabel 和 texts.launcherBlockedLabel 分别是铃铛在两种状态下的提示文字。每个文本字段最多接受 300 个字符。

colors.accent、colors.background、colors.text 和 colors.textSecondary 接受十六进制值或 CSS 颜色名称。Control Panel 表单会以这种方式校验其中每个字段以及 launcher.background/launcher.iconColor，最多 64 个字符。init 代码段则会接受 colors.* 的任何非空字符串，而不检查其格式或长度。对于 launcher.background/launcher.iconColor，它同样不检查格式，但会静默地将值截断为 64 个字符。

注意

深色模式调色板、launcher.zIndex 以及自定义 fontFamily 作为仅限 init 参数的附加字段提供。它们不会出现在下文所述的 Control Panel 表单中。

在 Control Panel 中管理

仅限面板管理的应用

Control Panel 卡片仅适用于 Web 平台处于面板管理模式的应用（参见 Web Push SDK 3.0）。对于代码段配置的应用，请如上所示在 init 代码段中设置 subscriptionWidget。

对于面板管理的应用，前往 Settings → Configure platforms → Web。提示和铃铛在那里是两张独立的卡片，各有自己的 On/Off 徽章和 Configure 按钮：

• Subscription invitation 编辑提示：Invitation（布局、位置、图标）、When to show（触发方式、延迟、频次限制）、Texts 和 Colors。
• Subscription bell 编辑启动器：位置、图片 URL、宽度/高度、背景色和图标颜色，以及它自己的提示文字。

每张卡片的 Configure 按钮都会在表单旁打开一个实时预览。当该卡片自己的开关关闭时，预览不会绘制任何内容。开启后，预览上方的下拉菜单可在未决定访问者的请求和已屏蔽访问者的说明之间切换。保存某张卡片只会替换面板中该小组件配置副本的对应部分——另一张卡片的设置以及您网站上的 WebSDK init 代码段均不受影响。

当应用处于面板管理状态时，任一卡片中保存的值都会覆盖网站 init 代码段中相同的键。

3. 从代码中控制提示

小组件包加载完成后，会在 Pushwoosh.moduleRegistry.subscriptionWidget 发布一个 API：

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

当 prompt.enabled 为 false 时，show() 和 toggle() 不起作用，对于已经订阅的访问者也不起作用。打开提示会触发 show-subscription-widget 事件，关闭它会触发 hide-subscription-widget 事件：

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

从旧版小组件迁移

只要网站的 subscriptionWidget.prompt.enabled 和 subscriptionWidget.launcher.enabled 都保持未设置或为 false，推送订阅按钮、自定义订阅弹窗和订阅提示就会继续按照各自页面中所述的方式工作。启用其中任何一个，都会停止这三者的加载，无论应用是代码段配置还是面板管理。

警告

小组件的早期版本使用单一的顶层 subscriptionWidget.enable 开关，而不是分开的 prompt.enabled/launcher.enabled。这种写法已不再被读取。仅设置了 enable: true 的代码段现在会让小组件完全关闭：提示和铃铛都不会绘制任何内容，WebSDK 会在控制台输出提示，指明应改为设置的两个字段，而这三个旧版小组件则会像从未设置过 subscriptionWidget 一样加载。将面板管理的应用切换到新小组件同样不会带入它所替代的旧小组件的设置——每张卡片都从自己的默认值开始。