Для получения кампаний необходимо отправить запрос `/choose`. В запросе должен быть указан селектор кампании, который вы задали при создании кампании.

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

---

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

!!!contrast API reference
[:icon-terminal: /ssapi/сhoose](https://openapi-v1.gravityfield.ai/ssapichoose-19695685e0)
!!!

### Типы кампаний
Метод `choose` поддерживает два типа кампаний: товарные и нетоварные. Тип указывается при создании кампании.

1. Товарные кампании:
- Это кампании с типом **Recommendations** (Рекомендации) и **Product listing** (Листинг товаров).
- В ответе эти кампании можно идентифицировать по `choices[].type = RECS_DECISION` и  `choices[].variations[].payload.type = RECS`.
- В ответе возвращаются только те параметры товаров, которые указаны в разделе **Product Fields** (Поля товара) в настройках фида.
- Для изменения списка полей обратитесь к вашему персональному менеджеру.
2. Нетоварные кампании:
- Это кампании с типом Custom JSON.
- В ответе эти кампании можно идентифицировать по `choices[].type = DECISION` и  `choices[].variations[].payload.type = CUSTOM_JSON`.

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

**Селектор кампании (selector):**
Укажите селектор для получения кампании, в которой он установлен. Если передать несколько селекторов, кампании в ответе будут упорядочены по алфавиту.

**Групповые селекторы (selector.groups):**
Используйте для получения кампаний, у которых установлен селектор группы кампаний (selector group).

**Implicit Pageview (options.isImplicitPageview):**
Добавьте этот параметр, чтобы передать информацию о просмотре страницы вместе с запросом.

!!!warning
Если вы будете использовать динамические фильтры, предварительно укажите их в **Dynamic filter fields** (Поля для использования в динамических фильтрах) в настройках фида.
!!!

=== Пример запроса:
```jsx
curl --request POST 
--url 'https://evs-01.gravityfield.ai/ssapi/choose'
--header 'content-type: application/json' 
--header 'Authorization: Bearer your-api-key' 
--data '
{
	"user": {
		"id": "638073ccfb53d530340043f2"
	},
	"session": {
		"custom": "E4EE9F9C-72AC-4036-A3A6-F3874E779FC1"
	},
	"context": {
		"page": {
			"type": "PRODUCT",
			"data": ["123456"],
			"location": "shop.ru/p/red_socks_123456/",
			"lng": "MOW"
		},
		"device": {
			"userAgent": "AliExpress/13.2 (Linux; Android 13; SM-A536B; Build/1452)",
			"ip": "54.100.200.255"
		},
		"pageAttributes": {
			"source": "mobileApp",
			"geo": "Moscow",
			"crm_segment": "loyal_buyers"
		},
		"user_time": "2024-08-14T17:28:31+02:00"
	},
	"selector": {
		"names": [
			"pdp_recs",
			"pdp_CTA_test"
		]
	},
	"options": {
		"isImplicitPageview": true,
		"returnAnalyticsMetadata": false,
		"recsProductData": {
			"skusOnly": true,
			"fieldFilter": {
				"whatever": "whatever"
			}
		}
	}
}'
```   
=== Если пользователь новый (взаимодействует с сайтом в первый раз), кампании для него запрашиваются без `user` и `session`:
    
```jsx
curl --request POST  
--url 'https://evs-01.gravityfield.ai/ssapi/choose'
--header 'content-type: application/json' 
--header 'Authorization: Bearer: your-api-key' 
--data '
{
	"context": {
		"page": {
			"type": "HOMEPAGE",
			"data": [],
			"location": "shop.ru"
		},
		"device": {
			"userAgent": "Mozilla/5.0 (Linux; U; Android 8.1.0; zh-CN; EML-AL00 Build/HUAWEIEML-AL00) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/57.0.2987.108 baidu.sogo.uc.UCBrowser/11.9.4.974 UWS/2.13.1.48 Mobile Safari/537.36 AliApp(DingTalk/4.5.11) com.alibaba.android.rimet/10487439 Channel/227200 language/zh-CN"
		}
	},
	"selector": {
		"names": [
			"test1"
		]
	}
}
```
===

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

1. Если вы передали `selector.names` или `selector.groups`, и в ответе вернулось `{ "choices": [] } `, то платформа не нашла кампании с таким селектором в этой секции. Проверьте, что вы используете API ключ той секции, где есть кампания с таким селектором.
2. Если в ответе есть товарная кампания с вариацией, но в `slots` пусто, то стратегия не возвращает товары. Проверьте, что контекст запроса соответсвует контексту стратегии, нет слишком жестких ограничей (правил, динамических фильтров)
3. В ответе на `choose` запрос товарной кампании возвращаются только те параметры товаров, которые указаны в **Product Fields** (Поля товара) в настройках фида. Для изменения списка указанных параметров обратитесь к вашему персональному менеджеру.

=== Пример ответа (кампании с типом Recommendations/Product listing):

```json
{
	"choices": [
		{
			"id": 1,
			"name": "Campaign_Name",
			"type": "RECS_DECISION",
			"variations": [
				{
					"id": 1,
					"name": "Variation_Name",
					"payload": {
						"type": "RECS",
						"data": {
							"custom": {
								// Custom Code, описанный в вариации
							},
							"slots": [
								{
									"sku": "12345",
									"productData": {},
									"slotId": "63gf:63bd:63bc4d2:63bdba:63bc91:63a17:0:104445:0:3:0"
								}
														]
						}
					}
				}
			],
			"groups": [],
			"decisionId": "63bca:63bd:63bc48d2:63bdba"
		}
	],
	"session": {
		"sl": "C7-EA-48-83-5706"
	},
	"user": {
		"slid": "63c7fgn6"
	}
}
```
===

!!!
В [Postman](https://www.postman.com/gravity-field/gravity-field-server-side-api/api/3f70ef78-2d32-42e4-bbd3-f98fe4ddde34) содержится больше примеров использования параметров
!!!

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

1. Установите таймаут для ожидания ответа от сервера.
2. Если полученный ответ имеет статус, отличный от `200`, выполните одно из следующих действий:
	- Не отображайте ничего.
	- Отобразите заглушку, например, стандартный баннер или предустановленный набор продуктов в виджете.

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

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