站内产品推荐

Web SDK 可以在您的网站上显示产品推荐：在产品页、购物车、目录页或 404 页面上。产品来自应用程序的产品目录。有两种显示方式：

• Widget： 添加一个带有 data-pw-recommendations 属性的元素，SDK 会在其中填充产品网格。
• Headless API： 调用 Pushwoosh.recommendations.fetch，并使用您自己的标记渲染产品。

一个实际示例是 Pushwoosh 演示商店 pushon.pushwoosh.com。它在 404 页面上有一个 widget 区块，在产品页和购物车中有 headless 区块。

前提条件

• Web SDK 3.96.0 或更高版本，按照 Web push SDK 3.0 中的说明从 Pushwoosh CDN 加载。web-push-notifications npm 包目前尚不包含推荐功能。
• 应用程序的产品目录中有产品。
• 已为应用程序开启站内推荐。请参阅开启站内推荐。

开启站内推荐

每个应用程序需要单独开启，因为提供区块数据的 feed 是公开的，不需要 API token。在此之前，feed 会返回错误，区块保持为空。

要在控制面板中开启站内推荐：

1. 为应用程序转到 内容 → 产品目录。
2. 点击 On-site recommendations。
3. 开启 Show recommendations on my website。
4. 在 Website domains 中，输入将显示区块的网站域名，每行一个。例如 shop.example.com。
5. 点击 保存。

保存后：

• Website domains 会按 Pushwoosh 存储的形式显示域名：添加了 https://、转为小写并去除重复项。请检查列表中是否有拼写错误。
• 区块仅在列出的网站上加载。如果将 Website domains 留空，区块会在任何网站上加载。
• 更改会在一分钟内生效。

如果您无法访问控制面板，请联系 Pushwoosh 支持团队或您的 Customer Success Manager，为应用程序开启站内推荐。请提供应用程序代码以及您网站的域名。

推荐策略

策略	显示内容	所需数据
viewed	该访客最近浏览过的产品。对于已登录的访客，其 user ID 下浏览过的产品排在最前面。	通过 trackProductView 发送的产品浏览。
bestsellers_30d	应用程序过去 30 天内最畅销的产品。已售罄的产品会被跳过。	包含订单商品的订单事件。
also_bought	经常与指定产品一起购买或浏览的产品。已售罄的产品会被跳过。	通过 trackProductView 发送的产品浏览、订单事件，或任何其他携带产品 ID 的事件。请参阅跟踪产品活动。请求需要提供产品 ID。

当某个策略没有可显示的内容时，feed 会改为提供回退策略。回退策略默认为 bestsellers_30d。将其设置为 none 即可改为获得空响应。响应始终会告诉您实际提供的是哪个策略，以便您更改区块的标题。

跟踪产品浏览

viewed 和 also_bought 策略使用产品浏览数据。在每个产品页上，在 SDK 就绪后调用 trackProductView：

Pushwoosh.push(() => {
  Pushwoosh.trackProductView({
    id: 'SKU-123',
    name: 'Linen shirt',
    price: 49.9,
    currency: 'USD',
    category: 'Shirts',
    url: 'https://shop.example.com/linen-shirt',
    imageUrl: 'https://shop.example.com/img/linen-shirt.jpg',
  });
});

只有 id 是必填项。请使用与产品目录中相同的产品 ID。SDK 会发送 PW_ProductView 事件，并跳过 30 秒内对同一产品的重复浏览，因此重新加载页面不会算作第二次浏览。

发送订单事件

bestsellers_30d 策略只统计来自订单事件的销量，并且它是每个区块的默认回退策略。当访客下单时，发送 PW_OrderCreated：

Pushwoosh.push((api) => {
  api.postEvent('PW_OrderCreated', {
    orderId: 'ORDER-10293',
    items: [
      { productId: 'SKU-123', quantity: 1 },
      { productId: 'SKU-456', quantity: 2 },
    ],
  });
});

orderId 是必填项，因为没有它的订单不会被统计。在 items 中，请使用与产品目录中相同的产品 ID。当订单发生变化时，发送带有相同 orderId 和 items 的 PW_OrderUpdated。如需改为从您的服务器发送订单事件，请参阅Bestsellers：将商品添加到订单事件中。

添加 widget 区块

在区块应出现的位置添加一个带有 data-pw-recommendations 属性的元素。SDK 只会在包含此类元素的页面上加载 widget。

<div
  data-pw-recommendations
  data-pw-strategy="also_bought"
  data-pw-product-id="SKU-123"
  data-pw-fallback="bestsellers_30d"
  data-pw-limit="4"
  data-pw-title="Bought together"
  data-pw-fallback-title="Popular right now"
  data-pw-block="pdp-also-bought"
  data-pw-min-height="260"
></div>

属性	描述
data-pw-recommendations	将元素标记为推荐区块。必填。
data-pw-strategy	viewed、bestsellers_30d 或 also_bought。默认为 bestsellers_30d。
data-pw-fallback	主策略没有内容时提供的策略：viewed、bestsellers_30d、also_bought 或 none。默认为 bestsellers_30d。
data-pw-limit	产品数量，从 1 到 12。默认为 6。
data-pw-product-id	屏幕上显示的产品。also_bought 必填。
data-pw-exclude	以逗号分隔的不显示的产品 ID，例如已在购物车中的产品。最多 50 个。
data-pw-block	区块名称。它会添加到产品链接和点击事件中，以便您在分析中区分不同区块。
data-pw-title	区块标题。
data-pw-fallback-title	提供回退策略时显示的标题，例如用 “Popular right now” 代替 “You viewed”。
data-pw-min-height	区块加载时预留的空间，用于避免布局偏移。数字按像素解析。也可以使用任何 CSS 长度值。

Widget 会显示每个产品的图片、名称和价格，并链接到产品页。产品链接带有 utm_medium=onsite。点击产品会发送 PW_RecommendationClick 事件，其中包含区块名称、策略和产品位置。

当您更改任何 data-pw-* 属性时，区块会重新加载。例如，当屏幕上的产品在不重新加载页面的情况下发生变化时，请更新 data-pw-product-id。

典型页面的区块

页面	策略	需设置的属性
产品页	also_bought	data-pw-product-id 设为屏幕上的产品，data-pw-exclude 设为相同的 ID
购物车	also_bought	data-pw-product-id 设为购物车中的某个产品，data-pw-exclude 设为购物车中的所有产品
目录页或首页	bestsellers_30d	—
404 页面	viewed	data-pw-fallback="bestsellers_30d" 和 data-pw-fallback-title，以便首次访问的访客看到热门产品

区块状态

Widget 会在区块元素上设置 data-pw-state 属性：

• loading： 产品正在加载。
• ready： 产品已显示。
• empty： 策略和回退策略都没有产品。区块保持为空。
• error： 产品未能加载。区块保持为空。

使用该状态可以隐藏空区块周围您自己的框架或标题：

.recommendations-frame:has([data-pw-state="empty"], [data-pw-state="error"]) {
  display: none;
}

设置 widget 样式

Widget 在 shadow DOM 中渲染，因此您网站的 CSS 无法作用于其内容。请改为在区块元素上设置以下自定义属性：

属性	描述	默认值
--pw-reco-font	字体系列	继承自页面
--pw-reco-accent	价格颜色	当前文本颜色
--pw-reco-radius	产品图片的圆角半径	8px
--pw-reco-columns	网格列数。在宽度不超过 600px 的屏幕上，网格始终为 2 列。	尽可能多

[data-pw-recommendations] {
  --pw-reco-columns: 4;
  --pw-reco-radius: 0;
  --pw-reco-accent: #337ab7;
}

如需更精细的样式设置，标题、网格和每张产品卡片分别以 title、grid 和 card CSS parts 的形式公开，例如 [data-pw-recommendations]::part(card)。

单页应用

默认情况下，SDK 只在就绪时查找一次区块。如果您的网站稍后才渲染区块，例如在单页应用中导航时，请在 init 调用中将 recommendations.spa 设置为 true：

Pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX',
  // other initialization parameters...
  recommendations: {
    spa: true,
  },
}]);

将 XXXXX-XXXXX 替换为您的应用程序代码。

此后，SDK 会持续监视页面，并在区块出现时加载 widget。

如果即使页面包含 data-pw-recommendations 元素也要禁用 widget，请将 recommendations.widget 设置为 false。Headless API 仍可继续使用。

使用您自己的标记渲染区块

当 widget 的布局不适合您的设计时，请使用 headless API。使用 Pushwoosh.recommendations.fetch 请求产品，并使用 Pushwoosh.recommendations.trackClick 上报点击：

Pushwoosh.push(async () => {
  const request = {
    strategy: 'also_bought',
    productId: 'SKU-123',
    exclude: ['SKU-123'],
    fallback: 'bestsellers_30d',
    limit: 4,
    block: 'pdp-also-bought',
  };
  const { items, strategy } = await Pushwoosh.recommendations.fetch(request);

  const title = strategy === request.strategy ? 'Bought together' : 'Popular right now';
  renderBlock(title, items, (item, index) => {
    Pushwoosh.recommendations.trackClick({
      block: request.block,
      strategy,
      productId: item.id,
      position: index + 1,
    });
  });
});

fetch 接受与 widget 属性相同的参数：strategy、fallback、limit、productId、exclude 和 block。它返回：

• items： 产品列表。每个产品包含 id、title、description、image_url、url、price、price_formatted、old_price_formatted（仅适用于促销产品）、currency、category 和 sku。
• strategy： 实际提供的策略。当提供的是回退策略时，它与请求的策略不同；当响应为空时，它为 none。

如果请求失败，fetch 会抛出错误。请捕获该错误并隐藏区块。

trackClick 会发送 PW_RecommendationClick 事件。即使点击打开了另一个页面，该事件也会被送达。position 是产品在区块中的位置，从 1 开始。

未同意通信时的行为

如果访客与 Pushwoosh 的通信已被禁用，例如在 init 调用中设置了 communicationEnabled: false（请参阅管理 Web 推送通知的用户同意）：

• trackProductView 和 trackClick 不会发送任何内容。
• 区块仍会显示产品，但请求不会识别访客。viewed 策略没有可用的历史记录，因此会提供回退策略。

访客启用通信后，产品浏览和点击会重新被跟踪。