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

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

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

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

---

## 1️⃣ Создание кампании

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

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

---

## 2️⃣ Настройка сценария

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

📚 Подробнее см. 
- [🧠 Как создать стратегию](/personalization/Recs/manage_recs)
- [🧠 Как создать АПИ кампанию](/personalization/Campaigns/api_campaigns.md)

---

## 3️⃣ Получение рекомендаций через API `/choose`

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

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

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

```json
{
  "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](/Integration/api_integration/personalization/choose.md)

---

## 4️⃣ Отправка события взаимодействия `/engagement`

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

### 🔁 Зачем это нужно?

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

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

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

### 📥 Пример запроса

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

```json
{
  "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](/Integration/api_integration/personalization/engagement.md)
📚 Подробнее о [SLOT_CLICK и других взаимодействиях](/glossary.md#slot_click)

---

## ❓ FAQ

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

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

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

---

## 📎 Примеры и отладка

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

---