# 🔌 Как создать рекомендательную API-кампанию

В этом гайде разберём, как создать API-кампанию в Gravity Field, которая будет рекомендовать товары к конкретному товару на странице. Такой сценарий часто используется на карточке товара (PDP) — чтобы показать похожие или сопутствующие товары.

Рекомендательные API-кампании позволяют возвращать персонализированные подборки товаров по запросу со стороны фронта. Это гибкий и мощный способ интеграции Gravity Field с мобильными приложениями, SPA и любыми кастомными интерфейсами.

Далее пошагово рассмотрим весь процесс — от интерфейса до запроса на /choose.

1. Перейдите в раздел API кампании
2. Нажмите Создать кампанию
3. Укажите:
   • Название кампании
   • Тип кампании: Recommendations
   • Selector — идентификатор вызова из API (например, pdp_recs)

📌 Кампания с типом Recommendations будет активироваться вызовом метода /choose с этим селектором.

1. Перейдите к созданию сценария (Experience)
2. Установите таргетинг:
   • Тип страницы: PRODUCT
3. Укажите шаблон (опционально)
4. Добавьте рекомендательную стратегию:
   • Можно использовать одну или несколько стратегий
   • Поддерживаются алгоритмы: Similar Items, Affinity, Popularity и др.
   • Настройте динамические фильтры (например, исключение текущего SKU)

📚 Подробнее см.

• 🧠 Как создать стратегию
• 🧠 Как создать АПИ кампанию

Для получения рекомендаций отправьте POST-запрос на:

POST https://evs.gravityfield.ai/ssapi/choose

Пример тела запроса:

{
  "user": { "id": "638073ccfb53d530340043f2" },
  "session": { "custom": "E4EE9F9C-72AC-4036-A3A6-F3874E779FC1" },
  "context": {
    "page": {
      "type": "PRODUCT",
      "data": ["123456"],
      "location": "shop.ru/p/red_socks_123456/",
      "lng": "MOW"
    },
    "device": {
      "userAgent": "AliExpress/13.2",
      "ip": "54.100.200.255"
    },
    "pageAttributes": {
      "source": "mobileApp",
      "geo": "Moscow",
      "crm_segment": "loyal_buyers"
    },
    "user_time": "2024-08-14T17:28:31+02:00"
  },
  "selector": {
    "names": ["pdp_recs"]
  },
  "options": {
    "isImplicitPageview": true,
    "returnAnalyticsMetadata": true,
    "recsProductData": {
      "skusOnly": true
    }
  }
}

📚 См. также API Choose

После отображения рекомендаций фиксируйте действия пользователя (например, клик по товару).

Вызов метода /engagement необходим, чтобы:

• Отслеживать взаимодействия пользователей (клики, показы)
• Обеспечивать работу аналитики и отчётов
• Корректно считать метрики A/B тестов и стратегий
• Обучать рекомендательные модели

Если не отправлять engagement, система не будет знать, какие рекомендации были интересны пользователю — и не сможет улучшать выдачу.

POST https://evs.gravityfield.ai/ssapi/engagement

{
  "user": { "id": "638073ccfb53d530340043f2" },
  "session": { "custom": "E4EE9F9C-72AC-4036-A3A6-F3874E779FC1" },
  "context": {
    "page": {
      "type": "PRODUCT",
      "data": ["123456"],
      "location": "shop.ru/p/red_socks_123456/"
    },
    "device": {
      "userAgent": "Mozilla/5.0",
      "ip": "8.8.8.8"
    }
  },
  "engagements": [
    {
      "type": "SLOT_CLICK",
      "decisionId": "abc123:ver1:exp1:cam1",
      "slotId": "abc123:ver1:exp1:cam1:slot001"
    }
  ]
}

📚 См. также API Engagement 📚 Подробнее о SLOT_CLICK и других взаимодействиях

Q: Можно ли использовать разные стратегии для одного селектора?
A: Да. Укажите их в сценарии — Gravity сам выберет подходящую по контексту или fallback-алгоритму.

Q: Обязательно ли передавать IP и User-Agent?
A: Да, это влияет на гео-таргетинг и идентификацию устройства.

Q: Где посмотреть метрики кампании?
A: В разделе Отчёты → Кампании и Отчёты → Стратегии.

• Используйте returnAnalyticsMetadata: true, чтобы получить decisionId и slotId
• Обязательно вызывайте /engagement после отображения рекомендаций — это критично для корректной аналитики