Для получения рекламы через API V2 отправьте запрос `/choose` и передайте идентификатор рекламного плейсмента в `data[].placementId`. !!! Подробнее о настройке рекламных кампаний: [Рекламные кампании](/retail_media/ad_campaigns/index.md) !!! --- ## choose: запрос рекламы для плейсмента !!!contrast API reference [:icon-terminal: POST /choose](https://openapi-v2.gravityfield.ai/get-campaign-14039236e0) !!! 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 из ответа. Подробнее: [Взаимодействия](./engagement.md). ### Пояснения к параметрам запроса **Placement ID (`data[].placementId`):** Идентификатор рекламного места, созданного в интерфейсе Gravity Ads. Один запрос `/choose` может содержать несколько элементов `data[]`, если нужно запросить несколько плейсментов. **Context (`ctx`):** Контекст страницы или экрана. Для `CATEGORY` передавайте иерархию категорий в `ctx.data`, для `PRODUCT` - SKU товара. Значения должны совпадать с фидом и настройками таргетинга. Подробнее: [Контекст](../context.md). **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[]`. !!!warning Если вы используете динамические фильтры или request-time rules, предварительно добавьте соответствующие поля в **Dynamic filter fields** в настройках фида. !!! === Пример запроса: ```jsx 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 конкретного товара. | === Сокращённый фрагмент ответа: ```json { "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. Не повторяйте запрос бесконечно: повторные запросы могут исказить статистику показов. ### Лимиты по количеству запросов [!ref icon=":icon-tab:"](../../rate_limits.md)