Взаимодействия

Для рекламной платформы важно передавать не только факт запроса плейсмента, но и взаимодействия пользователя с рекламным местом, креативом и товарами. Эти события используются для расчёта показов, видимых показов, CTR, эффективности товарных слотов и последующей оптимизации кампаний.

В API V2 tracking URL рекомендуется брать из ответа /choose. Для этого передайте options.isBuildEngagementUrl: true.

engagement: передача взаимодействий с рекламой

API reference

GET /engagement

Порядок действий после запроса рекламы

Когда пользователь открывает страницу или экран с рекламным плейсментом, вызовите /choose, передав placementId.
Если вы передали options.isImplicitImpression: false, обработайте variables.onImpression, если этот handler есть в ответе. Обычно ему соответствует Ad Impression (AIMP).
Когда рекламное место попало в область видимости как минимум на 50% в течение 1 секунды, обработайте variables.onVisibleImpression, если этот handler есть в ответе. Обычно ему соответствует Visible Impression (WRIMP).
Когда пользователь кликает по рекламному блоку, баннеру или CTA, обработайте variables.onClick, если этот handler есть в ответе. Обычно ему соответствует Ad Click (ADCLICK). У креатива может не быть кликовой ссылки, тогда click-handler может отсутствовать.
Для товарных кампаний дополнительно используйте product-level события из products.slots[].events[]: visible_impression для видимых товарных слотов и click для кликов по конкретному товару.

Где брать tracking URL

Tracking URL приходят в ответе /choose, если включён options.isBuildEngagementUrl.

Уровень	Где искать	Когда использовать
Рекламный блок	`content.events[].urls[]`	AIMP, WRIMP, ADCLICK и другие события всего рекламного юнита.
Товарный слот	`products.slots[].events[].urls[]`	`visible_impression` и `click` конкретного товара.

Клиенту не нужно вручную собирать query-параметры tracking URL. Вызовите все URL из подходящего urls[].

Content-level события

Content-level события связаны с handler-ами из variables. Объект variables и любой ключ variables.on* опциональны: если handler отсутствует, не отправляйте соответствующее content-level событие.

Не привязывайтесь к значению action внутри variables. Используйте имя handler-а:

Handler	Какой `content.events[].type` искать
`onImpression`	`AIMP`
`onVisibleImpression`	`WRIMP`
`onClick`	`ADCLICK`

{
  "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?..."]
    }
  ]
}

Принцип работы:

Проверьте наличие нужного handler-а в variables.
По имени handler-а выберите ожидаемый content.events[].type.
Найдите событие с таким type в content.events[].
Вызовите все URL из найденного events[].urls[].

Если variables отсутствует, нужного handler-а нет или в content.events[] нет подходящего type, ничего не отправляйте для этого content-level события.

{
  "options": {
    "isBuildEngagementUrl": true
  }
}

curl --request GET
--url 'https://evs-01.gravityfield.ai/v2/engagement?eventId=EVENT_ID&type=WRIMP&sec=YOUR_SECTION_ID'

Какие события отправлять

Что отправлять	Когда
`variables.onImpression` -> `AIMP`	После запроса рекламного плейсмента, если `isImplicitImpression: false` и handler вернулся в ответе.
`variables.onVisibleImpression` -> `WRIMP`	Один раз, когда рекламный блок стал видим пользователю как минимум на `50%` в течение `1` секунды.
`variables.onClick` -> `ADCLICK`	Когда пользователь взаимодействует с кликабельным рекламным блоком, если handler вернулся в ответе.
`slot.visible_impression`	Для товарных кампаний: когда конкретная карточка товара попала в область видимости. Это не показ всего товарного виджета.
`slot.click`	Для товарных кампаний: когда пользователь совершил любое осмысленное действие с карточкой товара: переход на карточку товара, добавление в корзину, добавление в избранное и т.п.

Для товарной рекламы не заменяйте product-level события из products.slots[].events[] только событием рекламного блока. Иначе статистика по конкретным SKU и слотам будет неполной.

Если URL не пришли

Если в ответе /choose нет tracking URL, проверьте:

передан ли options.isBuildEngagementUrl: true;
возвращается ли в UI-слой исходный events[], а не преобразованная модель без tracking URL;
настроены ли рекламный плейсмент, кампания и формат креатива;
не отправляете ли вы product-level события по баннерной кампании без товарных слотов.

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

/integration/api_integration/rate_limits/