# Начало интеграции

# Коллекция запросов

У API-документации есть коллекция запросов с примерами.

# Базовый URL

Используйте базовый URL:

https://evs-01.gravityfield.ai/v2

Все endpoint-ы V2 вызываются без префикса /ssapi:

POST https://evs-01.gravityfield.ai/v2/visit
POST https://evs-01.gravityfield.ai/v2/event
POST https://evs-01.gravityfield.ai/v2/choose

# Авторизация

API V2 использует bearer authentication. Передавайте API-ключ в заголовке Authorization:

--header 'Authorization: Bearer YOUR_API_KEY'

API-ключ создаётся в аккаунте Gravity Field. Подробнее: Управление API-ключами.

# `sec`: идентификатор секции

В каждом основном POST-запросе передавайте sec - идентификатор секции Gravity Field.

{
  "sec": "YOUR_SECTION_ID"
}

Если API-ключ не относится к указанной секции, API вернёт ошибку авторизации.

# Идентификация пользователя

В V2 пользователь и сессия передаются в объекте user:

{
  "user": {
    "uid": "USER_UID",
    "ses": "SESSION_ID"
  }
}

Правила хранения:

uid храните между сессиями пользователя;
ses храните для текущей сессии приложения или сайта;
после ответов /user, /visit, /event и /choose обновляйте локально значения user.uid и user.ses, если они пришли в ответе.

Если пользователь новый, первый запрос можно отправить без uid и ses. Gateway создаст пользователя и вернёт актуальные идентификаторы в ответе.

Если у вас есть собственный внешний идентификатор пользователя, передавайте его в user.custom. Для user.custom нужно также передавать user.ses.

# Когда передавать `uid` и `ses`

Ситуация	Что передавать
Новый пользователь	Можно передать пустой `user` или не передавать `uid`/`ses`.
Пользователь уже был на сайте или в приложении	Передайте сохранённый `uid`.
Продолжается та же сессия	Передайте сохранённый `uid` и текущий `ses`.
Началась новая app/browser session	Передайте `uid`, а `ses` можно не передавать, чтобы API выдал новую сессию.
Используется внешний ID клиента	Передайте `user.custom` и `user.ses`.

uid нужен для непрерывности истории пользователя. ses нужен для группировки действий внутри текущей сессии. В мобильных приложениях обычно uid хранится в persistent storage, а ses - только в памяти текущего запуска приложения.

# Когда `uid` и `ses` возвращаются в ответе

API может вернуть объект user в ответах /user, /visit, /event и /choose.

Обычно user.uid и user.ses возвращаются, когда:

пользователь новый и API создал для него идентификаторы;
запрос пришёл с uid, но без ses, и API создал новую сессию;
API обновил состояние пользователя или сессии;
endpoint возвращает user вместе с campaigns[] или data[].

Если в ответе нет user, uid или ses, это не означает ошибку. Оставьте локально сохранённые значения без изменений и используйте их в следующих запросах.

Правило обновления простое:

if (response.user?.uid) {
  saveUid(response.user.uid);
}

if (response.user?.ses) {
  saveSession(response.user.ses);
}

Подробный пример первого запроса: POST /user.

# Общий контекст

В V2 контекст страницы или экрана передаётся в ctx:

{
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://example.com/product/sku-123"
  }
}

Поддерживаемые значения ctx.type:

HOMEPAGE
SEARCH
PRODUCT
CATEGORY
CART
OTHER

Для PRODUCT и CATEGORY передавайте непустой ctx.data. Значения в ctx.data должны совпадать с идентификаторами товаров или категорий из фида и настройками таргетинга.

# Device

В каждом основном POST-запросе передавайте объект device. Минимально полезный набор:

{
  "device": {
    "ua": "Mozilla/5.0 ...",
    "ip": "192.168.0.1",
    "userTime": "2026-06-03T15:00:00+03:00"
  }
}

Для мобильных приложений также можно передавать device.id, tracking status и permission status, если эти данные доступны.

# Опции

В options можно запросить дополнительные данные или изменить поведение endpoint-а:

Опция	Где используется	Назначение
`isReturnCounter`	`/user`, `/visit`, `/event`, `/choose`	Вернуть сегменты и условия пользователя.
`isReturnUserInfo`	`/user`, `/visit`, `/event`, `/choose`	Вернуть расширенную информацию о пользователе.
`isReturnAnalyticsMetadata`	`/choose`	Вернуть дополнительные аналитические метаданные.
`isBuildEngagementUrl`	`/choose`	Сгенерировать tracking URL в `content.events[].urls[]` и `products.slots[].events[].urls[]`.
`isImplicitPageview`	`/choose`	Учесть pageview вместе с запросом контента.

Для manual rendering обычно включают isBuildEngagementUrl: true, чтобы не собирать engagement-запросы вручную. Подробнее: Передача взаимодействий пользователя с кампаниями.