Web 收件箱小组件

将 Web 消息收件箱集成到您的网站中，可显著提高转化率。一个即用型的 Web 收件箱小组件开箱即用，订阅了与用户通信所需的所有方法。只需将该小组件集成到您的网站中，并自定义其外观以适应您的品牌即可。

设置 inboxWidget.enable: true 会为访问者的设备注册收件箱投递，即使访问者尚未授予推送通知权限，因此它可以触达从未订阅过推送的访问者。

关于 SDK 版本的重要说明 (v3.66.0+)

从 3.66.0 版本开始，在访问者登录之前，其设备会通过与其浏览器绑定的硬件 ID 进行跟踪。如果访问者在调用 registerUser 之前清除了其网站数据、更换了浏览器或更换了设备，则该跟踪会中断。他们之前的消息历史记录会丢失，即使在访问者登录后也不会结转。

先决条件

要为网站集成消息收件箱，请遵循指南。

集成小组件

在初始化 Pushwoosh WebSDK 时，添加 inboxWidget 参数：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox'
  }
}]);

触发器

要渲染小组件，您应为其指定一个触发元素。页面上的任何 DOM 元素都可以作为触发器。将其 ID 指定为“pwInbox”，或在初始化 SDK 时为 triggerId 参数分配任何自定义 ID。 当 WebSDK 初始化后，未读消息徽章会显示在触发元素上。一旦点击触发元素，小组件就会出现在页面上。

定位

默认情况下，小组件位于离触发元素最近的屏幕边框的相反方向。 您可以通过配置参数设置小组件的位置：

示例

Pushwoosh.push(['init', {

  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    position: 'top'
  }
}]);

默认情况下，inboxWidget 应放在结束的 </body> 标签之前。 如下例所示，在页面上的任何位置渲染小组件：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {

    enable: true,
    triggerId: 'pwInbox',
    appendTo: '.widget-parent-element-class'
  }
}]);

父元素的搜索是通过 querySelector 执行的，因此需要明确指定类、id 或元素。

自定义小组件

自定义文本

要自定义小组件文本，请添加 emptyInboxTitle 和 emptyInboxText 参数：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    title: 'Inbox',                                 // 小组件标题
    emptyInboxTitle: 'You\'re all caught up',       // 空收件箱小组件标题
    emptyInboxText: 'There are no new messages. Stay tuned!'    // 空收件箱小组件文本
  }
}]);

结果如下所示：

自定义外观

要自定义小组件的外观，请使用以下参数：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    bgColor: '#ffffff',         // 小组件背景
    borderColor: 'transparent', // 小组件边框颜色
    borderRadius: 4,            // 小组件边框半径 (px)
    widgetWidth: 350,           // 小组件宽度 (px)
    zIndex: 100                 // z-index
  }
}]);

未读消息计数徽章可按如下方式自定义：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    badgeBgColor: '#ff4c00',    // 徽章颜色
    badgeTextColor: '#ffffff'   // 徽章文本颜色
  }
}]);

要自定义文本属性，请添加以下代码：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    textColor: '#333333',                       // 文本颜色
    fontFamily: 'Helvetica, Arial, sans-serif', // 字体
    messageTitleColor: '#7a7a7a',               // 消息标题颜色
    timeTextColor: '#c4c4c4',                   // 时间戳文本颜色
    emptyInboxTitleColor: '#333333',            // 空收件箱标题颜色
    emptyInboxTextColor: '#7a7a7a'              // 空收件箱文本颜色
  }
}]);

最后，您可以指定空收件箱的图标：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    emptyInboxIconUrl: 'https://pushon.pushwoosh.com/images/icon-empty-inbox.png'   // 图标的 URL 路径
  }
}]);

自定义单元格布局

小组件以四种单元格布局之一（classic、banner、captioned 或 carousel）绘制消息——与控制面板中的营销活动预览显示的布局相同。如果布局无法用消息所携带的内容进行渲染，则会降级为 classic：banner 需要主图，captioned 需要主图以及标题和正文，而 carousel 需要至少一张幻灯片以及标题和正文。

要自定义布局的外观，请使用以下参数：

示例

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    unreadDotColor: '#ff4c00',    // classic 头像上的未读点
    avatarBgColor: '#e6e6e6',     // classic 头像背景
    avatarTextColor: '#333333',   // classic 头像首字母颜色
    avatarSize: 52,               // classic 头像大小 (px)
    mediaRadius: 8,               // banner/captioned/carousel 媒体的圆角半径 (px)
    slideCaptionColor: '#ffffff', // carousel 幻灯片标题文本颜色
    slideScrimColor: '#000000',  // carousel 幻灯片标题背景遮罩
    pagerDotActiveColor: '#ff4c00', // carousel 活动页面点
    pagerDotColor: '#c4c4c4'      // carousel 非活动页面点
  }
}]);

恢复 3.75 版本之前的 classic 单元格

设置 inboxWidget.legacyClassicCell: true 以保留 classic 单元格的先前外观——一个 40px 的图标列，而不是 52px 的圆形头像，没有未读点，并且正文不被截断。banner、captioned 和 carousel 布局不受此选项影响。

在 Control Panel 中管理

要求

• 站点从 Pushwoosh CDN 加载 Web SDK，如卡片上所述。无论 Settings source 是站点上的 init 代码段还是本页面（参见 Web Push SDK 3.0），该卡片均可使用，但所需的 SDK 版本取决于该来源：
  • 站点上的 init 代码段：Web SDK 3.93.1 或更高版本。较旧的 SDK 会忽略该卡片，仅从代码段读取 inboxWidget。
  • 本页面：卡片中的值需要 Web SDK 3.92 或更高版本，下文所述的 npm 关闭功能需要 3.93.0 或更高版本。
• 页面上有用于打开收件箱的元素，默认为 #pwInbox。如果缺少该元素，收件箱将无法打开，浏览器控制台会显示 Error during Pushwoosh initialization 错误，其中会指出缺少的元素以及在何处更改其 ID。
• 对于通过 npm 安装 SDK 的站点，卡片可以关闭小组件，但无法开启，因为小组件由站点自行构建。

要在 Control Panel 中设置小组件：

1. 前往 Settings → Configure platforms → Web。

2. 在 Inbox widget 卡片上，点击 Configure。

   

3. 开启 Show the inbox on the site。

4. 填写您希望在面板中管理的字段，其余字段留空。留空的字段不会被保存，因此代码段中的值或 SDK 默认值仍然生效。将 ID of the element that opens the inbox 和 Insert into (CSS selector) 留空，可使 triggerId 和 appendTo 保留在代码段中，紧邻它们所指向的标记。

5. 在预览中检查效果。在 With messages 和 No messages 之间切换，查看两种状态。

   

6. 保存表单。Width, px 接受 200 到 1200 之间的整数，Corner radius, px 接受 0 到 64 之间的整数。其他任何值都会在字段下方显示错误，且不会被保存。

卡片与代码段如何配合

卡片中保存的值会逐个键地覆盖 init 代码段中相同的 inboxWidget 键。每个字段对应一个键：

分区	字段	inboxWidget 键
Placement	ID of the element that opens the inbox	triggerId
Placement	Opens	position
Placement	Insert into (CSS selector)	appendTo
Texts	Widget title	title
Texts	Title when there are no messages	emptyInboxTitle
Texts	Text when there are no messages	emptyInboxText
Texts	Image when there are no messages (URL)	emptyInboxIconUrl
Appearance	Width, px (200–1200)	widgetWidth
Appearance	Corner radius, px (0–64)	borderRadius
Appearance	Font	fontFamily
Appearance	Background, Text, Border	bgColor, textColor, borderColor
Appearance	Counter background, Counter text, Unread mark	badgeBgColor, badgeTextColor, unreadDotColor

卡片中没有的键，例如单元格布局参数和 legacyClassicCell，始终从代码段读取。

Show the inbox on the site 开关的工作方式相同。在面板中保存该开关之前，卡片徽章显示 Set in the snippet，由代码段的 enable 决定小组件是否显示。保存开关后，徽章显示 On 或 Off，卡片将覆盖代码段：

• Off 会隐藏小组件，即使代码段设置了 enable: true。
• On 会显示小组件，即使代码段中根本没有 inboxWidget。与 enable: true 一样，它会为访问者注册收件箱投递，无需推送权限。

保存的更改会在一分钟内、下次加载页面时生效于站点。

要将小组件交还给代码段管理，请点击卡片上的 Return to snippet 并确认。只要卡片中保存了任何内容，该按钮就会出现。它会删除面板中保存的所有收件箱设置，站点将重新使用其代码段中的 inboxWidget 设置。

API

要打开或关闭小组件，请使用以下 API 方法：

示例

Pushwoosh.pwinboxWidget.toggle(open?: boolean);

打开小组件会从服务器刷新它，最多每 30 秒一次——一个独立的 App 收件箱消息通过一个没有推送的渠道传输，因此在页面加载之间没有其他东西会通知新消息的到来。