Контекст `ctx`

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

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

{
  "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. Подробнее о настройке региональных вариантов данных: Мультиязычность и мультирегиональность.

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

`HOMEPAGE`

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

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

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

`CATEGORY`

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

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

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

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

`PRODUCT`

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

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

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

`CART`

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

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

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

`SEARCH`

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

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

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

`OTHER`

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

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

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

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

{
  "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 относится к текущей странице, экрану или запросу.

{
  "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 используются в динамических фильтрах или правилах, которые применяются во время запроса, заранее согласуйте эти поля с настройками фида и кампаний.

Контекст ctx

Структура ctx

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

HOMEPAGE

CATEGORY

PRODUCT

CART

SEARCH

OTHER