Docs

Кампании

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

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

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

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

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

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

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

Context (ctx): Передавайте текущую страницу, экран или условия, которые важны именно для этого запроса. ctx влияет на таргетинг, выбор кампании, рекомендации и аналитику. Подробнее о типах контекста и формате ctx.data: Контекст.

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

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

Подробные правила передачи ctx.attributes: Контекст.

{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "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"
  },
  "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?..."
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

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

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

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

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

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

© Copyright 2026. All rights reserved.