# Кампании

Для получения контента кампании необходимо отправить запрос /choose. В API V2 кампанию можно запросить по selector, group, campaignId или placementId.

Подробнее ознакомиться с процессом создания кампаний можно в следующей статье: API кампании

# choose: запрос кампаний

API reference

POST /choose

# Основные сценарии

Selector flow - placement известен заранее. Передайте data[].selector.
Activation flow - кампания активировалась через /visit или /event. Передайте data[].campaignId.

# Пояснения к параметрам запроса

Selector (data[].selector): Укажите selector кампании, который задан при создании API-кампании.

Campaign ID (data[].campaignId): Используйте, если /visit или /event вернул кампанию в campaigns[].

Implicit Pageview (options.isImplicitPageview): Добавьте этот параметр, чтобы передать просмотр страницы вместе с запросом кампании.

Engagement URLs (options.isBuildEngagementUrl): Добавьте этот параметр, чтобы Gateway сгенерировал готовые tracking URL в content.events[].urls[] и products.slots[].events[].urls[]. Эти URL затем используются для отправки engagement без ручной сборки query-параметров.

# Options

В options передаются настройки всего /choose запроса.

Параметр	Назначение
`isImplicitPageview`	Учитывает просмотр страницы вместе с `/choose`. Используйте только один раз на страницу или экран, если отдельно не вызываете `/visit`.
`isBuildEngagementUrl`	Генерирует готовые tracking URL для content-level и product-level engagement.
`isReturnAnalyticsMetadata`	Возвращает дополнительные аналитические данные, если они нужны вашему приложению.
`isReturnCounter`	Возвращает данные по сегментам и условиям пользователя, если они нужны для диагностики или кастомной логики.
`isReturnUserInfo`	Возвращает расширенную информацию о пользователе.

Для ручного рендеринга обычно включают isBuildEngagementUrl: true, чтобы не собирать /engagement URL вручную.

# Content options (`data[].option`)

Внутри элемента data[] можно передавать настройки конкретного запроса кампании или selector.

Для товарных рекомендаций чаще всего используются:

skusOnly: true - вернуть только SKU товаров без полного набора полей;
fields - ограничить список полей товара, которые должны вернуться в ответе.

{
  "data": [
    {
      "selector": "homepage-recommendations",
      "option": {
        "skusOnly": false,
        "fields": ["sku", "name", "price", "imageUrl"]
      }
    }
  ]
}

Если fields не передан, состав товарных полей зависит от настроек кампании и фида.

# Attributes

В API V2 есть два основных места для дополнительных атрибутов:

Поле	Когда использовать
`ctx.attributes`	Атрибуты текущей страницы, экрана или запроса: источник, регион, тип витрины, CRM-сегмент, флаг эксперимента.
`user.attributes`	Атрибуты пользователя, которые известны вашей системе: loyalty tier, город доставки, тип клиента, признак авторизации.

ctx.attributes обычно используется для таргетинга и условий, завязанных на текущий контекст. user.attributes - для признаков пользователя, которые не зависят от конкретной страницы.

{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141",
    "attributes": {
      "loyaltyTier": "gold",
      "isLoggedIn": "true"
    }
  },
  "ctx": {
    "type": "HOMEPAGE",
    "data": [],
    "location": "https://shop.ru/",
    "attributes": {
      "source": "mobileApp",
      "region": "Moscow",
      "crm_segment": "loyal_buyers"
    }
  }
}

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

curl --request POST 
--url 'https://evs-01.gravityfield.ai/v2/choose'
--header 'content-type: application/json' 
--header 'Authorization: Bearer your-api-key' 
--data '
{
  "sec": "YOUR_SECTION_ID",
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141",
    "attributes": {
      "loyaltyTier": "gold"
    }
  },
  "ctx": {
    "type": "HOMEPAGE",
    "data": [],
    "location": "https://shop.ru/",
    "attributes": {
      "source": "mobileApp",
      "region": "Moscow"
    }
  },
  "device": {
    "ua": "Mozilla/5.0",
    "ip": "54.100.200.255"
  },
  "options": {
    "isImplicitPageview": true,
    "isBuildEngagementUrl": true
  },
  "data": [
    {
      "selector": "homepage-recommendations",
      "option": {
        "skusOnly": false,
        "fields": ["sku", "name", "price", "imageUrl"]
      }
    }
  ]
}'

curl --request POST 
--url 'https://evs-01.gravityfield.ai/v2/choose'
--header 'content-type: application/json' 
--header 'Authorization: Bearer your-api-key' 
--data '
{
  "sec": "YOUR_SECTION_ID",
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://shop.ru/product/sku-123"
  },
  "device": {
    "ua": "Mozilla/5.0",
    "ip": "54.100.200.255"
  },
  "options": {
    "isBuildEngagementUrl": true
  },
  "data": [
    {
      "campaignId": "665f0b000000000000000001"
    }
  ]
}'

{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "data": [
    {
      "selector": "homepage-recommendations",
      "payload": [
        {
          "variationId": "665f0d000000000000000001",
          "contents": [
            {
              "contentId": "665f0e000000000000000001",
              "variables": {
                "onImpression": {
                  "action": "IMP"
                },
                "onVisibleImpression": {
                  "action": "WRIMP"
                }
              },
              "events": [
                {
                  "type": "IMP",
                  "urls": [
                    "https://evs-01.gravityfield.ai/v2/engagement?..."
                  ]
                },
                {
                  "type": "WRIMP",
                  "urls": [
                    "https://evs-01.gravityfield.ai/v2/engagement?..."
                  ]
                }
              ],
              "products": {
                "slots": [
                  {
                    "slotId": "665f0f000000000000000001:1",
                    "item": {
                      "sku": "sku-456"
                    },
                    "events": [
                      {
                        "type": "visible_impression",
                        "urls": [
                          "https://evs-01.gravityfield.ai/v2/engagement?..."
                        ]
                      },
                      {
                        "type": "click",
                        "urls": [
                          "https://evs-01.gravityfield.ai/v2/engagement?..."
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

# Обработка ответа

Если /choose вернул пустой data, платформа не нашла подходящую кампанию для текущего пользователя, контекста и selector.
Если в ответе есть content.events[].urls[], вызовите эти URL при показе, видимом показе, клике или другом действии, заданном в variables.on*.
Для товарных рекомендаций используйте products.slots[].events[], а не только content-level events[].

Подробнее про отправку tracking URL: Передача взаимодействий пользователя с кампаниями.

# Лимиты по количеству запросов

Лимиты по количеству запросов

/integration/api_integration/rate_limits/