Работа с рекомендательными виджетами

Вы можете использовать JS SDK API для получения рекомендаций в рамках любого типа веб-кампаний непосредственно в коде своего проекта. Результат возвращается в JSON-формате. Вот некоторые преимущества, которые дает использование данного API:

• полный контроль над тем, как отображать рекомендации;
• возможность добавлять кастомный прелоадер-скелетон;
• дополнительная или пост-обработка данных из фида перед тем как отобразить виджет;
• контроль над fallback - вы можете не отображать виджет, если стратегия ушла в fallback или сделать запрос к другой стратегии в этом случае;
• использование динамических фильтров;
• подмена контекста в запросе.

Получение рекомендаций

Функция используется для получения рекомендаций на основе заданной стратегии или нескольких стратегий. Она позволяет запрашивать рекомендации с индивидуальными настройками и исключать дубликаты между разными стратегиями.

Синтаксис

GF.Recommendations.get(strategy, options, callback)

Параметры:

GF.Recommendations.get('1364138cfe9b4f979a044a32', {
  maxProducts: 10,
}, function (err, data) {
  if (err) {
    // error handling
    return;
  }

  const recData = data;
});

{
  "wId": "63a98ddd11fad4619a0c05b0",
  "name": "Sample strategy name",
  "fId": "6336f2f22b77b4c6da026ad4",
  "fallback": false,
  "slots": [
    {
      "item": {
        "sku": "1000001",
        "group_id": "1000001",
        "categories": [
          "Женское",
          "Платья"
        ],
        "in_stock": true,
        "name": "Платье из вискозы и шерсти",
        "price": "29900",
        "url": "...html",
        "image_url": "https://...image.png"
      },
      "fallback": false,
      "strId": 3
    }
  ]
}

GF.Recommendations.get(
  ['6406d885d9ea38c202022a73', '1364138cfe9b4f979a044a32'],
  {
    maxProducts: 5,
    realtimeRules: [],
  },
  function (err, data) {
    console.log(data);
  },
);

GF.Recommendations.get(
  [
    { id: '1364138cfe9b4f979a044a32' },
    { id: '6406d885d9ea38c202022a73', maxProducts: 2 },
  ],
  {
    maxProducts: 5,
    realtimeRules: [],
    context: { type: 'PRODUCT', data: ['123123'], lng: 'spb' },
  },
  function (err, data) {
    console.log(data);
  },
);

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

Чтобы отслеживать аналитику рекомендательного виджета, который вы вручную добавили на свой сайт с помощью Client-Side API, необходимо определенным образом разметить виджет и вызвать дополнительную функцию трекинга. Для настройки трекинга используются данные, полученные в ответе API.

Блок, содержащий товары виджета, должен иметь дата-атрибуты:

• data-sl-widget-id - wId из JSON-ответа, идентификатор стратегии;
• data-sl-feed-id - fId из JSON-ответа, идентификатор фида;
• data-sl-fallback - fallback из JSON-ответа, статус fallback стратегии;
• data-sl-external - опциональный признак внешнего виджета. Используйте значение true, если виджет рендерится вне кампании Gravity Field.

Блок, содержащий товар, должен иметь дата-атрибуты:

• data-sl-product-id - sku из JSON-ответа, артикул товара;
• data-sl-strategy-id - strId из JSON-ответа, идентификатор типа стратегии, может отличаться у разных слотов;
• data-sl-product-fallback - fallback из JSON-ответа товара, статус fallback конкретного товара;
• data-sl-product-slot - порядковый номер товара в виджете, начинается с 0.

Допускается произвольный уровень вложенности между блоком-контейнером и товаров.

<div 
   data-sl-widget-id="6308a8277asdf28f7b055a9d" 
   data-sl-feed-id="6308a8277asdf28f7b055a9d"
   data-sl-fallback="false" 
>
	<div 
     data-sl-product-fallback="false" 
     data-sl-product-id="123456" 
     data-sl-strategy-id="4"
     data-sl-product-slot="0" 
  >
     ...
  </div>
	
</div>

После того как виджет вставлен на страницу, вызовите функцию трекинга:

Синтаксис

GF.Recommendations.track(element, variationData)

Параметры:

Объект variationData:

{
  var: '${slVariationId}',
  ver: '${slVersionId}',
  exp: '${slExperienceId}',
  cam: '${slTagId}',
}

const element = document.querySelector('[data-sl-widget-id="6308a8277asdf28f7b055a9d"]');

GF.Recommendations.track(element, {
  var: '${slVariationId}',
  ver: '${slVersionId}',
  exp: '${slExperienceId}',
  cam: '${slTagId}',
});

События виджета

После вызова GF.Recommendations.track контейнер виджета может отправлять DOM-события:

element.addEventListener('gf_pimp', function (event) {
  console.log(event.detail.slots);
});

Динамические правила

В некоторых случаях может появиться потребность в создании правила для стратегии, которое будет зависеть от условий, имеющихся в момент просмотра страницы. Для таких случаев существуют динамические фильтры, которые позволяют создавать правила в реальном времени и получать рекомендации на основании данных, полученных в ходе сеанса. Например, показывать товары по более высокой цене, чем те, которые пользователь просматривает в данный момент, или предлагать товары на основе известных данных о пользователе.

Распространные варианты использования

• Предложения по бесплатной доставке: рекомендуемые товары, которые попадают в ценовой диапазон, позволяющий пользователю получить бесплатную доставку (выше порогового значения).
• Рекомендовать товары в определенном диапазоне относительно просматриваемого товара, например, от 80% до 150% от текущей цены товара.
• Рекомендовать товары исходя из параметров URL, например, отфильтрованная страница категории по бренду.
• Рекомендовать товары исходя из количества бонусных баллов пользователя в системе лояльности.

Фильтры передаются как массив объектов realtimeRules в параметрах запроса рекомендаций.

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

GF.Recommendations.get(
  '6634e31af6df45aa130d31d8',
  {
    maxProducts: 20,
    realtimeRules: [
      {
        query: {
          conditions: [
            {
              field: 'categories',
              arguments: [
                {
                  action: 'equal',
                  value: ['Столы'],
                },
                {
                  action: 'equal',
                  value: ['Стулья'],
                },
              ],
            },
          ],
        },
        type: 'include',
        slots: [1],
      },
    ],
  },
  function (err, data) {
    // process data
  },
);

const currentProductPrice = 10000;
const minPrice = currentProductPrice * 0.8;
const maxPrice = currentProductPrice * 1.5;

GF.Recommendations.get(
  '6634e31af6df45aa130d31d8',
  {
    maxProducts: 20,
    realtimeRules: [
      {
        query: {
          conditions: [
            {
              field: 'price',
              arguments: [
                {
                  action: 'more',
                  value: [minPrice],
                },
              ],
            },
            {
              field: 'price',
              arguments: [
                {
                  action: 'less',
                  value: [maxPrice],
                },
              ],
            },
          ],
        },
        type: 'include',
        slots: [],
      },
    ],
  },
  function (err, data) {
    console.log(data.slots.map(function (slot) {
      return slot.item.price;
    }));
  },
);