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

!!!
Для рекламных плейсментов Gravity Ads используйте отдельный сценарий: [Получение рекламных кампаний](../retail_media/choose.md).
!!!

!!!
Подробнее ознакомиться с процессом создания кампаний можно в следующей статье: [API кампании](/personalization/Campaigns/api_campaigns.md)
!!!

---

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

!!!contrast API reference
[:icon-terminal: POST /choose](https://openapi-v2.gravityfield.ai/get-campaign-14039236e0)
!!!

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

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`: [Контекст](../context.md).

**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` - ограничить список полей товара, которые должны вернуться в ответе.

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

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

### Attributes

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

Подробные правила передачи `ctx.attributes`: [Контекст](../context.md).

```json
{
  "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 передавайте как строки. Используйте одинаковые названия и значения во всех каналах интеграции, если эти атрибуты применяются в таргетинге кампаний.

=== Пример запроса по selector:
```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": "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"]
      }
    }
  ]
}'
```
===

=== Пример запроса по campaignId:
```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": "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"
    }
  ]
}'
```
===

=== Пример ответа:
```json
{
  "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: [Передача взаимодействий пользователя с кампаниями](./engagement.md).

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

[!ref icon=":icon-tab:"](../../rate_limits.md)