# Контекст `ctx`

`ctx` описывает текущую страницу, экран или условия, которые важны именно для этого запроса. API V2 использует этот объект для таргетинга, активации кампаний, выбора рекомендаций, подбора рекламы и корректной аналитики.

Передавайте `ctx` во всех основных POST-запросах API V2: `/user`, `/visit`, `/event`, `/choose` и `/strategy`.

```json
{
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://shop.ru/product/sku-123"
  }
}
```

## Структура `ctx`

| Поле | Тип | Назначение |
| :--- | :--- | :--- |
| `type` | `string` | Тип текущей страницы или экрана: `HOMEPAGE`, `CATEGORY`, `PRODUCT`, `CART`, `SEARCH`, `OTHER`. |
| `data` | `string[]` | Основные данные контекста: SKU, категории, товары корзины или поисковый запрос. Формат зависит от `ctx.type`. |
| `location` | `string` | URL страницы, deep link или технический идентификатор экрана. |
| `referrer` | `string` | Предыдущая страница или внешний источник перехода, если доступен. |
| `lng` | `string` | Регион, город, склад или другой согласованный код зоны обслуживания. |
| `utm` | `object` | UTM-метки текущего перехода. |
| `attributes` | `object` | Дополнительные атрибуты текущего запроса для таргетинга и динамических условий. |

Минимально полезный `ctx` содержит `type`, `data` и `location`. Поля `referrer`, `utm` и `attributes` передавайте, если они используются в таргетинге, аналитике, фильтрах или правилах кампаний.

Если проект использует региональные цены, наличие, остатки или другие региональные параметры фида, передавайте `ctx.lng`. Подробнее о настройке региональных вариантов данных: [Мультиязычность и мультирегиональность](../../products_catalogues/multi_language.md).

## Типы контекста

### `HOMEPAGE`

Используйте для главной страницы сайта или стартового экрана приложения.

`ctx.data` можно передавать пустым массивом или не использовать.

```json
{
  "ctx": {
    "type": "HOMEPAGE",
    "data": [],
    "location": "https://shop.ru/"
  }
}
```

### `CATEGORY`

Используйте для страниц категорий, листингов и разделов каталога.

В `ctx.data` передавайте иерархию категорий от самой широкой к самой узкой. Значения должны совпадать с товарным фидом и настройками таргетинга.

```json
{
  "ctx": {
    "type": "CATEGORY",
    "data": ["Женщинам", "Обувь", "Кроссовки"],
    "location": "https://shop.ru/catalog/women/shoes/sneakers"
  }
}
```

Если в фиде категории хранятся как идентификаторы, передавайте идентификаторы. Если в фиде и настройках используются названия, передавайте названия в том же написании.

### `PRODUCT`

Используйте для карточки товара.

В `ctx.data` передавайте SKU текущего товара. SKU должен совпадать с идентификатором товара в фиде.

```json
{
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://shop.ru/product/sku-123"
  }
}
```

### `CART`

Используйте для корзины.

В `ctx.data` передавайте SKU всех товаров, которые находятся в корзине. Если корзина пуста, передавайте пустой массив.

```json
{
  "ctx": {
    "type": "CART",
    "data": ["sku-123", "sku-456", "sku-789"],
    "location": "https://shop.ru/cart"
  }
}
```

### `SEARCH`

Используйте для страницы или экрана поиска.

В `ctx.data` передавайте поисковый запрос одной строкой. Для пустого поиска передавайте пустой массив.

```json
{
  "ctx": {
    "type": "SEARCH",
    "data": ["белые кроссовки"],
    "location": "https://shop.ru/search?q=белые%20кроссовки"
  }
}
```

### `OTHER`

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

`ctx.data` можно передавать пустым массивом или не использовать.

```json
{
  "ctx": {
    "type": "OTHER",
    "data": [],
    "location": "https://shop.ru/help/delivery"
  }
}
```

## Полный пример

```json
{
  "ctx": {
    "type": "CATEGORY",
    "data": ["Женщинам", "Обувь", "Кроссовки"],
    "location": "https://shop.ru/catalog/women/shoes/sneakers",
    "referrer": "https://search.example/?q=кроссовки",
    "lng": "MOW",
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "summer-sale"
    },
    "attributes": {
      "source": "web",
      "region": "Moscow",
      "storeFormat": "marketplace",
      "crm_segment": "loyal_buyers"
    }
  }
}
```

`ctx.attributes` относится к текущей странице, экрану или запросу.

```json
{
  "ctx": {
    "type": "HOMEPAGE",
    "data": [],
    "attributes": {
      "source": "mobileApp",
      "region": "Moscow"
    }
  }
}
```

## Качество данных

- Значения в `ctx.data` должны использовать те же идентификаторы, что фид, настройки кампаний, рекламные плейсменты и правила таргетинга.
- Не смешивайте SKU, названия категорий и поисковые запросы в одном типе контекста: выбирайте `ctx.type` по текущей странице или экрану.
- Для `PRODUCT` передавайте SKU товара, для `CATEGORY` - иерархию категорий, для `CART` - SKU товаров корзины, для `SEARCH` - поисковый запрос.
- Передавайте `ctx.location`, если нужно различать страницы, экраны, источники активации или анализировать путь пользователя.
- Значения в `ctx.attributes` передавайте строками и используйте одинаковые названия ключей во всех каналах интеграции.
- Если `ctx.attributes` используются в динамических фильтрах или правилах, которые применяются во время запроса, заранее согласуйте эти поля с настройками фида и кампаний.