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

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

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

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

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

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

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

✅ Выполнена API-интеграция.
✅ У вас есть API-ключ и селектор.
✅ Команда разработки готова обрабатывать JSON-ответ и отображать контент.

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

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

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

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

2️⃣ Настройка сценария (Experience)

Сценарий управляет условиями показа (для кого и когда):

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

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

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

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

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

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

4️⃣ Настройка содержимого вариации

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

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

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

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

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

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

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

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

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

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

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

📤 Запрос

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

Пример запроса вызывающего кампанию с селектором PDP Recs Block 1:

{
    "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"] // дополнительные фильтры
        }
    }
}

🔸 Ответ

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

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

Перед публикацией убедитесь, что выполнены все шаги:

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