Товарные рекомендации на сайте

Web SDK может показывать товарные рекомендации на вашем сайте: на странице товара, в корзине, на странице каталога или на странице 404. Товары берутся из каталога товаров приложения. Показать их можно двумя способами:

Виджет: добавьте элемент с атрибутом data-pw-recommendations, и SDK заполнит его сеткой товаров.
Headless API: вызовите Pushwoosh.recommendations.fetch и отрисуйте товары в собственной разметке.

Живой пример — демо-магазин Pushwoosh по адресу pushon.pushwoosh.com. В нем есть блок-виджет на странице 404 и headless-блоки на странице товара и в корзине.

Предварительные требования

Web SDK версии 3.96.0 или выше, загруженный с CDN Pushwoosh, как описано в руководстве по Web Push SDK 3.0. npm-пакет web-push-notifications пока не поддерживает рекомендации.
Товары в каталоге товаров приложения.
Рекомендации на сайте, включенные для приложения. См. Включение рекомендаций на сайте.

Включение рекомендаций на сайте

Каждое приложение включается отдельно, потому что фид, который отдает блоки, публичный и не требует API-токена. До включения фид отвечает ошибкой, а блоки остаются пустыми.

Чтобы включить рекомендации на сайте в панели управления:

Перейдите в Контент → Каталог товаров для нужного приложения.
Нажмите On-site recommendations.
Включите Show recommendations on my website.
В поле Website domains введите домены сайтов, на которых будут показываться блоки, по одному в строке. Например, shop.example.com.
Нажмите Сохранить.

Панель On-site recommendations с включенным переключателем Show recommendations on my website, одним доменом в поле Website domains и кнопкой Save

После сохранения:

В поле Website domains домены показаны так, как их сохранил Pushwoosh: с добавленным https://, в нижнем регистре и без дубликатов. Проверьте список на опечатки.
Блоки загружаются только на перечисленных сайтах. Если оставить поле Website domains пустым, блоки будут загружаться на любом сайте.
Изменение вступает в силу в течение минуты.

Если у вас нет доступа к панели управления, попросите службу поддержки Pushwoosh или вашего Customer Success Manager включить рекомендации на сайте для приложения. Укажите код приложения и домены ваших сайтов.

Стратегии рекомендаций

Стратегия	Что показывает	Что нужно
`viewed`	Товары, которые этот посетитель недавно просматривал. Для авторизованного посетителя первыми идут товары, просмотренные под его user ID.	Просмотры товаров, отправленные с помощью `trackProductView`.
`bestsellers_30d`	Самые продаваемые товары приложения за последние 30 дней. Распроданные товары пропускаются.	События заказов с позициями заказа.
`also_bought`	Товары, которые часто покупают или просматривают вместе с заданным товаром. Распроданные товары пропускаются.	Просмотры товаров, отправленные с помощью `trackProductView`, события заказов или любые другие события, содержащие ID товара. См. Отслеживание активности по товарам. В запросе нужен ID товара.

Когда стратегии нечего показать, фид вместо нее отдает резервную стратегию. По умолчанию резервная стратегия — bestsellers_30d. Установите значение none, чтобы вместо этого получать пустой ответ. В ответе всегда указано, какая стратегия была отдана фактически, поэтому вы можете изменить заголовок блока.

Отслеживание просмотров товаров

Стратегии viewed и also_bought используют просмотры товаров. На каждой странице товара вызывайте trackProductView после того, как SDK будет готов:

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 товаров, что и в каталоге товаров. Когда заказ меняется, отправьте PW_OrderUpdated с теми же orderId и items. Чтобы отправлять события заказов со своего сервера, см. Бестселлеры: добавьте товары в события о заказах.

Добавление блока-виджета

Добавьте элемент с атрибутом data-pw-recommendations там, где должен появиться блок. SDK загружает виджет только на страницах, где есть такой элемент.

<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.

Виджет показывает изображение, название и цену каждого товара и ссылается на страницу товара. Ссылки на товары содержат 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`, чтобы новые посетители видели популярные товары

Состояния блока

Виджет устанавливает атрибут data-pw-state на элементе блока:

loading: товары загружаются.
ready: товары показаны.
empty: товаров нет ни у стратегии, ни у резервной стратегии. Блок остается пустым.
error: товары не загрузились. Блок остается пустым.

Используйте состояние, чтобы скрыть собственную рамку или заголовок вокруг пустого блока:

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

Стилизация виджета

Виджет отрисовывается внутри 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;
}

Для более тонкой стилизации заголовок, сетка и каждая карточка товара доступны как CSS parts title, grid и card, например [data-pw-recommendations]::part(card).

Одностраничные приложения

По умолчанию SDK ищет блоки один раз — когда он готов. Если ваш сайт отрисовывает блоки позже, например при навигации в одностраничном приложении, установите recommendations.spa в значение true в вызове init:

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

Замените XXXXX-XXXXX на ваш код приложения.

После этого SDK продолжает следить за страницей и загружает виджет, как только появляется блок.

Чтобы виджет не загружался, даже если на странице есть элементы data-pw-recommendations, установите recommendations.widget в значение false. Headless API при этом продолжает работать.

Отрисовка блоков в собственной разметке

Используйте 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 принимает те же параметры, что и атрибуты виджета: 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 для посетителя отключена, например с помощью communicationEnabled: false в вызове init (см. Управление согласием пользователя на получение веб-пуш-уведомлений):

trackProductView и trackClick ничего не отправляют.
Блоки по-прежнему показывают товары, но запрос не идентифицирует посетителя. У стратегии viewed нет истории, которую можно использовать, поэтому отдается резервная стратегия.

Как только посетитель включает коммуникацию, просмотры товаров и клики снова отслеживаются.