# API V2

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

API reference

OpenAPI V2

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

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

server-side получение персонализации или рекомендаций;
мобильное приложение с ручным 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.

# Чем 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 нужно вызвать в момент показа, видимого показа или клика.

# С чего начать

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

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