API V2

API V2 - это новый публичный Gateway API Gravity Field для server-side, web, mobile SDK и headless-сценариев. Он используется для сценариев персонализации Gravity Field и рекламной платформы Gravity Ads, когда приложение или backend клиента сами управляют HTTP-запросами, состоянием пользователя, рендерингом контента и отправкой tracking-событий.

API reference

OpenAPI V2

Когда использовать API V2

Используйте API V2, если вам нужен один из сценариев:

server-side получение персонализации или рекомендаций;
получение рекламных кампаний Gravity Ads для retail media плейсментов;
мобильное приложение с ручным HTTP-клиентом без готового UI-слоя SDK;
headless-интеграция, где ваш продукт сам рендерит контент;
inline-блоки, API-кампании и A/B-тесты по selector;
in-app сценарии, где кампания активируется через просмотр экрана или пользовательское событие.

Если у вас уже работает V1-интеграция через /ssapi/*, её не нужно срочно удалять. V2 можно внедрять постепенно: сначала на новых placements или в новом канале, затем переносить существующие сценарии.

Основные endpoints персонализации

Endpoint	Назначение
`POST /user`	Получить или создать пользователя и сессию без отправки события.
`POST /visit`	Передать pageview или screenview и получить активированные кампании.
`POST /event`	Передать бизнес-события: login, add to cart, purchase и кастомные события.
`POST /choose`	Получить контент кампании по `campaignId`, `selector`, `group` или `placementId`.
`POST /strategy`	Получить данные стратегии рекомендаций.
`GET /engagement`	Отправить tracking interaction по URL, который вернулся в ответе API.

Основные endpoints рекламной платформы

Endpoint	Назначение
`POST /user`	Получить или обновить пользователя и сессию перед запросом рекламного плейсмента.
`POST /choose`	Получить рекламную кампанию по `placementId`.
`GET /engagement`	Отправить рекламные interaction по URL из ответа `/choose`.

Чем V2 отличается от V1

V1	V2
`/ssapi/choose`, `/ssapi/event`, `/ssapi/page`, `/ssapi/engagement`	`/choose`, `/event`, `/visit`, `/engagement`
`context.page`	`ctx`
`user.slid` и `session.sl`	`user.uid` и `user.ses`
`events[].properties`	typed event data и `customProps`
engagement часто отправляется отдельным request body	tracking URL приходит в `content.events[].urls[]` и `products.slots[].events[].urls[]`, если включить `options.isBuildEngagementUrl`

Что меняется в контракте

Endpoint-ы.
В V2 используются короткие endpoint-ы относительно base URL /v2: /user, /visit, /event, /choose, /strategy, /engagement.

Идентификаторы пользователя.
В запросах используется объект user с полями uid, ses, custom и attributes. Если API вернул новые uid или ses, сохраните их и передавайте в следующих запросах.

Контекст.
Контекст передаётся в объекте ctx: type, data, location, lng, referrer, utm, attributes. Для PRODUCT и CATEGORY значение ctx.data обязательно. Подробнее: Контекст.

События.
В /event события передаются в массиве data[]. Основные поля события находятся на верхнем уровне объекта события, а произвольные параметры передаются в customProps.

Engagement.
Если в /choose передать options.isBuildEngagementUrl: true, Gateway вернёт готовые tracking URL в content.events[].urls[] и products.slots[].events[].urls[]. Эти URL нужно вызвать в момент показа, видимого показа или клика. В рекламной платформе content-level события выбираются по handler-ам variables.on*, а product-level события - в products.slots[].events[].

С чего начать

Настройте HTTP-клиент и авторизацию: Начало интеграции.
Настройте передачу контекста страницы или экрана: Контекст.
Выберите flow персонализации: /visit, /event, /choose.
Для рекламной платформы начните с /choose по placementId и подключите передачу взаимодействий.
Если переходите с V1, используйте краткую инструкцию по миграции.

Для Flutter-приложений с прямым HTTP-клиентом также доступен отдельный прикладной гайд: Гайд: Прямая API-интеграция для Flutter.