# 🔌 Создание API-кампании в Gravity Field

Эта инструкция поможет продактам, маркетологам и разработчикам создать и запустить API-кампанию — кампанию, где контент возвращается в виде JSON, а рендеринг реализуется на стороне клиента (вашего сайта или приложения).

---

## 🧠 Когда использовать API-кампании?

API-кампании подходят, если:

- Вы используете **мобильное приложение**, **SPA** или **серверный рендеринг**.
- Вам нужно **получить рекомендации, баннеры или другой контент через API**, а отрисовать его самостоятельно.
- Вы хотите управлять логикой показа в Gravity Field, но дизайн — на вашей стороне.
- Вы хотите протестировать backend-driven фичу, например поисковый провайдер, алгоритм ранжирования или другой feature flag. Подробнее: [Тестирование фич через API-кампании](./feature_testing_api_campaigns.md).

> В отличие от Web-кампаний, в API-кампаниях нет визуального редактора. Всё отображение реализуется вашей командой на стороне клиента.

---

## 🛠 Перед началом убедитесь, что:

- ✅ Выполнена [API-интеграция](https://docs.gravityfield.ai/integration/api_integration/).
- ✅ У вас есть [API-ключ и селектор](https://docs.gravityfield.ai/integration/api_integration/manage_api_keys/).
- ✅ Команда разработки готова обрабатывать JSON-ответ и отображать контент.

---

## 📌 Шаги создания API-кампании

### 1️⃣ Создание кампании

![](./assets/campaign_create_api.png)

1. Перейдите в раздел **Campaigns → API Campaigns**.
2. Нажмите **Создать кампанию**.
3. Укажите:

| Поле                    | Описание                                                                 |
|-------------------------|--------------------------------------------------------------------------|
| **Название кампании**   | Отображается в списке кампаний.                                         |
| **Комментарий и лейблы**| Удобно для навигации и фильтрации.                                      |
| **Status**              | Статус кампании:<br>— `Active` — будет доступна в API<br>— `Draft` — черновик<br>— `Paused` — временно отключена |
| **API-селектор**        | Уникальное имя для вызова кампании через API.                           |
| **Группа селекторов**   | Позволяет вызывать несколько кампаний одним запросом.                   |
| **Тип кампании**        | `Custom JSON` или `Recommendations JSON`.                              |

---

### 2️⃣ Настройка сценария (Experience)
![](./assets/campaign_create_api_exps.png)

Сценарий управляет **условиями показа** (для кого и когда):
- Нажмите **Add experience**
- Укажите:
  - Название сценария (например: «Для новых пользователей»)
  - Таргетинг (по сегменту, странице, времени и т.п.)
  - При необходимости — **расписание показа** (Set Schedule)

> Можно задать точные даты и время, когда сценарий будет активен, включая часовой пояс.

---

### 3️⃣ Создание вариации

Каждый сценарий может включать одну или несколько вариаций (например, для A/B теста).

Вариация содержит:

| Настройка                     | Описание                                                   |
|------------------------------|-------------------------------------------------------------|
| **Метод тестирования**       | A/B или динамическое распределение                         |
| **Ключевая метрика**         | Для выбора победителя теста (например, конверсия, CTR)      |
| **Stickiness**               | Привязка вариации к сессии или пользователю                |
| **Окно атрибуции**           | Период, когда действие пользователя будет учтено            |
| **Минимальная длительность** | Чтобы не завершать тест слишком рано                       |

---

### 4️⃣ Настройка содержимого вариации
![](./assets/campaign_create_api_code.png)

Нажмите ✏️ **Edit**, чтобы задать JSON-ответ:

- Для **Custom JSON**: вы указываете произвольный объект.
- Для **Recommendations JSON**: выбираете стратегию рекомендаций, а JSON содержит список товаров.

💡 Можно использовать переменные — например, для заголовка или изображения — и редактировать их в интерфейсе без правки кода. Подробнее: [Переменные в вариациях](./variables.md)

---

### 5️⃣ Предпросмотр и тестирование

Хотя в API-кампаниях нет встроенного визуального предпросмотра, вы можете:

- Отправить тестовый `choose`-запрос через Postman или curl.
- Проверить, что API возвращает нужный JSON.
- Убедиться, что клиентское приложение отображает результат корректно.

---

### 6️⃣ Активация и публикация кампании

Для полноценного запуска нужно активировать **и сценарий, и кампанию**:

- Установите статус сценария (Experience) в **Active**.
- Установите статус кампании в **Active**.
- Нажмите кнопку **Опубликовать** в верхней панели, чтобы применить изменения.

> ⚠️ Если сценарий активен, но сама кампания — в черновике, кампания показываться не будет.

---

## 🔄 Пример запроса и ответа

### 📤 Запрос
Для получения кампании из API Gravity Field необходимо отправить запрос в endpoint [choose](/Integration/api_integration/personalization/choose.md). В запросе должен быть указан селектор кампании, который вы [задали при создании кампании](./api_campaigns.md).

Пример запроса вызывающего кампанию с селектором `PDP Recs Block 1`:
```json
{
    "user": {
        "slid": "639c83a421b4a8749306d566" // идентификатор пользователя из одноимённой куки
    },
    "session": {
        "sl": "996C20A3-28A6-4DA0-8F19-6721332D19D4" // идентификатор сессии из куки _slsession
    },
    "context": {
        "page": { // контекст страницы
            "type": "PRODUCT", 
            "data": [ 
                "894"
            ],
            "lng": "34567890",
            "location": "https://shop.biz/nice-shirt-p76311.html",
            "referrer": "https://google.cz",
            "locale": "de_DE"
        },
        "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",
            "ip": "192.168.0.1"
        }
    },
    "selector": {
        "names": [
            "PDP Recs Block 1" // селектор вызываемой кампании, можно запрашивать сразу несколько
        ]
    },
    "options": {
        "isImplicitPageview": true, // если на странице нет скрипта, отправка просмотра страницы в аналитику платформы
        "recsProductData": {
            "skusOnly": true, // указание (не) возвращать информацию о товарах из фида
            "fieldFilter": ["fieldFilter"] // дополнительные фильтры
        }
    }
}
```

### 🔸 Ответ

```json
{
    "choices": [
        {
            "id": "65cdf9ec260afb0c050cd2e0", // идентификатор кампании
            "name": "PDP Recommendations Block 1", // название кампании
            "type": "RECS_DECISION", // тип ответа
            "variations": [
                {
                    "id": "65cdf9ec260afb0c050cd2e7", // идентификатор стратегии
                    "name": "Popularity", // тип стратегии
                    "payload": {
                        "type": "RECS", // тип кампании
                        "data": { 
                            "custom": { // JSON с переменные из вариации, заведенными в интерфейсе
                                "title": "Популярные товары"
                            },
                            "slots": [ // массив с рекомендованными товарами (только для рекомендательных кампаний)
                                {
                                    "sku": "19874", // идентификатор товара, как в фиде
                                    "productData": {},
                                    "slotId": "65cdf9ec260afb0c050cd2e0:65cdf9ec260afb0c050cd2e9:65cdf9ec260afb0c050cd2e3:65cdf9ec260afb0c050cd2e7:651c3871d5f72ba433096868:650dabce812954894a00a248:0:19874:0:3:0", // идентификатор слота, нужно возвращать в вызовах в engagememnt: SLOT_CLICK
                                    "fallback": false // информация о том, сработала целевая стратегия или произошёл фолбек в резервную
                                },
                                {
                                    "sku": "19794",
                                    "productData": {},
                                    "slotId": "65cdf9ec260afb0c050cd2e0:65cdf9ec260afb0c050cd2e9:65cdf9ec260afb0c050cd2e3:65cdf9ec260afb0c050cd2e7:651c3871d5f72ba433096868:650dabce812954894a00a248:0:19794:0:3:1",
                                    "fallback": false
                                },

...

"groups": [],
            "decisionId": "65cdf9ec260afb0c050cd2e0:65cdf9ec260afb0c050cd2e9:65cdf9ec260afb0c050cd2e3:65cdf9ec260afb0c050cd2e7" // идентификатор ответа, нужно возвращать в вызовах в engagememnt: WRIMP и CLICK (для рекомендаций CLICK не используется)
        }
    ],
    "session": {
        "sl": "98EC002F-E3EF-49FD-B845-71E88E7CD58A" // идентификатор сессии
    },
    "cookies": [
        {
            "name": "_slsession",
            "value": "98EC002F-E3EF-49FD-B845-71E88E7CD58A", // сессионная кука для установки в браузер пользователя
            "maxAge": "1800"
        }
    ]
}
```

## ✅ Финальный чек-лист для успешного запуска

Перед публикацией убедитесь, что выполнены все шаги:
- [x] Получен API-ключ
- [x] Создана кампания с нужным типом и задан API-селектор
- [x] Добавлен хотя бы один сценарий с таргетингом
- [x] Настроены вариации с JSON-содержимым
- [x] Проведено тестирование API-ответа
- [x] Активированы сценарий и кампания
- [x] Кампания опубликована

## 📚 Полезные материалы

- [Web Integration](/Integration/api_integration/api_integration.md)
- [API ключи](/Integration/api_integration/manage_api_keys.md)
- [API логи](/Integration/api_integration/api_logs.md)
- [Тестирование фич через API-кампании](./feature_testing_api_campaigns.md)
- [Переменные](/personalization/Campaigns/variables.md)
- [Структура кампании](./campaign_structure.md)
- [Настройки таргетинга и условий показа](./targeting_schedule.md)