Docs

Получение рекламных кампаний

Для получения рекламы через API V2 отправьте запрос /choose и передайте идентификатор рекламного плейсмента в data[].placementId.

choose: запрос рекламы для плейсмента

API V2 использует общий Gateway endpoint /choose для персонализации и рекламной платформы. В рекламном сценарии основной ключ выбора - placementId: по нему платформа находит подходящие баннерные или товарные кампании, учитывая контекст страницы, пользователя, таргетинг, ставки и доступность инвентаря.

Основной flow

  1. Определите рекламный плейсмент, который должен быть отрисован на странице или экране.
  2. Вызовите /choose с data[].placementId, актуальными user.uid, user.ses, ctx и device.
  3. Передайте options.isBuildEngagementUrl: true, чтобы получить готовые tracking URL для рекламных событий.
  4. Отрисуйте полученный рекламный юнит или fallback.
  5. Передайте взаимодействия через URL из ответа. Подробнее: Взаимодействия.

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

Placement ID (data[].placementId): Идентификатор рекламного места, созданного в интерфейсе Gravity Ads. Один запрос /choose может содержать несколько элементов data[], если нужно запросить несколько плейсментов.

Context (ctx): Контекст страницы или экрана. Для CATEGORY передавайте иерархию категорий в ctx.data, для PRODUCT - SKU товара. Значения должны совпадать с фидом и настройками таргетинга. Подробнее: Контекст.

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

Engagement URLs (options.isBuildEngagementUrl): Включите, чтобы Gateway вернул готовые tracking URL. Для рекламной платформы это особенно важно: клиенту не нужно вручную собирать параметры tracking-события.

Implicit Pageview (options.isImplicitPageview): Используйте, если просмотр страницы нужно учесть вместе с запросом /choose и вы не вызываете /visit отдельно.

Implicit Impression (options.isImplicitImpression): Используйте только для рекламных плейсментов, где согласован неявный учёт потенциального показа вместе с /choose. Если вы передаёте isImplicitImpression: false, обработайте variables.onImpression, если этот handler вернулся в креативе, и вызовите соответствующие URL из content.events[].

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": "CATEGORY",
    "data": [
      "Parent category",
      "Sub category"
    ],
    "lng": "MOW",
    "location": "https://shop.ru/cat/1",
    "attributes": {
      "source": "web",
      "region": "Moscow"
    }
  },
  "device": {
    "userTime": "2026-06-03T15:00:00+03:00",
    "ua": "Mozilla/5.0",
    "ip": "54.100.200.255"
  },
  "options": {
    "isImplicitPageview": true,
    "isImplicitImpression": false,
    "isBuildEngagementUrl": true
  },
  "data": [
    {
      "placementId": "646689c3404f91f26103faa6"
    }
  ]
}'

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

Ответ зависит от формата кампании и настроек плейсмента:

  • для баннерной рекламы вернутся данные креатива, ссылка, рекламные метаданные и tracking URL;
  • для товарной рекламы вернутся рекламные товары, slotId для каждого слота, product fields из фида и tracking URL для товарных событий;
  • если подходящей рекламы нет, плейсмент можно не показывать или отрисовать согласованный fallback.

Для корректной аналитики не отбрасывайте данные, которые API вернул вместе с рекламным юнитом и товарными слотами:

Данные Зачем нужны
Рекламные метаданные Идентификаторы кампании, группы, креатива, теста, erid и другие поля, если они вернулись в response. Точный набор зависит от формата кампании и настроек плейсмента.
slotId Идентификатор товарного слота для product-level событий, если в ответе есть товарные слоты.
content.events[].urls[] Готовые URL для content-level событий: AIMP, WRIMP, ADCLICK.
products.slots[].events[].urls[] Готовые URL для product-level событий: visible impression и click конкретного товара. 
{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "data": [
    {
      "placementId": "646689c3404f91f26103faa6",
      "payload": [
        {
          "decisionId": "ads:...",
          "ord": {
            "erid": "test-erid"
          },
          "adSetId": "67051a995eadbaa5390785f5",
          "campaignId": "67051a995eadbaa5390785f4",
          "creativeId": "67051a995eadbaa5390785f6",
          "testId": "67051a995eadbaa5390785f8",
          "contents": [
            {
              "contentId": "67051a995eadbaa5390785f6",
              "deliveryMethod": "API",
              "contentType": "CUSTOM_JSON",
              "custom": {
                "json": "{\"title\":\"Здесь могут быть любые параметры креатива\"}"
              },
              "variables": {
                "onImpression": {
                  "action": "AIMP"
                },
                "onVisibleImpression": {
                  "action": "WRIMP"
                },
                "onClick": {
                  "action": "ADCLICK"
                }
              },
              "events": [
                {
                  "type": "AIMP",
                  "urls": [
                    "https://evs-01.gravityfield.ai/v2/engagement?..."
                  ]
                },
                {
                  "type": "WRIMP",
                  "urls": [
                    "https://evs-01.gravityfield.ai/v2/engagement?..."
                  ]
                },
                {
                  "type": "ADCLICK",
                  "urls": [
                    "https://evs-01.gravityfield.ai/v2/engagement?..."
                  ]
                }
              ],
              "products": {
                "strategyId": "67051a995eadbaa5390785f9",
                "fallback": false,
                "slots": [
                  {
                    "slotId": "670519f27352da07900f3654:67051a995eadbaa5390785f5:0",
                    "campaignData": {
                      "placementId": "646689c3404f91f26103faa6",
                      "campaignId": "67051a995eadbaa5390785f4",
                      "adSetId": "67051a995eadbaa5390785f5",
                      "creativeId": "67051a995eadbaa5390785f6",
                      "testId": "67051a995eadbaa5390785f8",
                      "decisionId": "ads:...",
                      "deliveryMethod": "API",
                      "contentType": "CUSTOM_JSON",
                      "ord": {
                        "erid": "test-erid"
                      }
                    },
                    "item": {
                      "sku": "123",
                      "categories": ["Category A"],
                      "price": "1000",
                      "url": "https://shop.ru/product/123"
                    },
                    "strId": 1,
                    "fallback": false,
                    "events": [
                      {
                        "type": "visible_impression",
                        "urls": [
                          "https://evs-01.gravityfield.ai/v2/engagement?..."
                        ]
                      },
                      {
                        "type": "click",
                        "urls": [
                          "https://evs-01.gravityfield.ai/v2/engagement?..."
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Объект variables и любые ключи variables.on* опциональны. Если handler отсутствует, не отправляйте соответствующее content-level событие. Не привязывайте обработку к значению action внутри variables: используйте имя handler-а (onImpression, onVisibleImpression, onClick) и соответствующий content.events[].type.

Если список товаров пустой или рекламный блок не вернулся, не отправляйте кликовые события по отсутствующему рекламному юниту. Для учёта ёмкости инвентаря используйте variables.onImpression, только если этот handler вернулся в ответе.

Слайдер баннеров

Для слайдера один placementId может вернуть несколько элементов payload[]. Каждый элемент payload[] соответствует отдельному выбранному креативу и содержит собственные decisionId, contentId, metadata и tracking URL.

Если для плейсмента возвращается настройка контейнера, она приходит в data[].custom.json. Например, для carousel-сценария там может быть указан тип компонента и количество payload-элементов.

Обработка ошибок

  1. Установите таймаут ожидания ответа от Gateway.
  2. Если ответ не 200, не блокируйте страницу или экран.
  3. В зависимости от UX сценария не показывайте плейсмент или отрисуйте стандартный fallback.
  4. Не повторяйте запрос бесконечно: повторные запросы могут исказить статистику показов.

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

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

© Copyright 2026. All rights reserved.