События

Для сбора статистики, расчёта целей и оптимизации кампаний необходимо передавать в Gravity Field информацию о действиях пользователя.

event: передача событий

В API V2 события передаются в массиве data[]. Дополнительные свойства события передавайте в customProps.

Передавайте вместе с событием актуальный ctx, чтобы кампания могла учитывать текущую страницу, экран или текущие условия запроса. Подробнее: Контекст.

Активация и таргетинг

/event не только сохраняет пользовательское событие для статистики. Ответ также может содержать кампании, подходящие под переданное событие.

Если в ответе вернулся непустой campaigns[], это означает:

1. Для одного из переданных событий нашлась кампания.
2. Пользователь и текущий ctx подходят под условия этой кампании.
3. campaigns[].campaignId можно использовать в /choose, чтобы получить контент.

Если campaigns[] пустой или отсутствует, событие всё равно принято для аналитики и целей, но для текущего пользователя не нашлось кампании под это событие.

curl --request POST \
  --url 'https://evs-01.gravityfield.ai/v2/event' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer your-api-key' \
  --data '
{
  "sec": "YOUR_SECTION_ID",
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "ctx": {
    "type": "CART",
    "data": [],
    "location": "https://shop.ru/cart"
  },
  "device": {
    "ua": "Mozilla/5.0",
    "ip": "54.100.200.255"
  },
  "data": [
    {
      "type": "purchase-v1",
      "name": "Purchase",
      "value": 1990,
      "currency": "RUB",
      "uniqueTransactionId": "order-100500",
      "cart": [
        {
          "productId": "sku-123",
          "quantity": 1,
          "itemPrice": 1990
        }
      ],
      "customProps": {
        "paymentMethod": "card"
      }
    }
  ]
}'

{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  },
  "campaigns": [
    {
      "campaignId": "665f0b000000000000000001",
      "experienceId": "665f0c000000000000000001",
      "trigger": "event",
      "priority": 10,
      "delayTime": 0
    }
  ]
}

Как использовать ответ

1. Сохраните обновлённые user.uid и user.ses, если они пришли в ответе.
2. Если campaigns[] пустой, дополнительных действий для показа кампании не требуется.
3. Если campaigns[] не пустой, выберите кампанию и передайте её campaignId в /choose.

/event отвечает за запись события и список подходящих кампаний. Контент, вариация и tracking URL возвращаются только в /choose.

Структура запроса

Данные устройства

Общие поля события

Объект товарной позиции в cart:

Справочник событий

Добавление в корзину

Отправляйте событие после подтверждённого добавления. quantity и value относятся только к текущему действию, а cart отражает полное состояние корзины после него.

{
  "type": "add-to-cart-v1",
  "name": "Add to Cart",
  "productId": "sku-4324-bg",
  "quantity": 2,
  "value": 24.68,
  "currency": "RUB",
  "cart": [
    {
      "productId": "sku-4324-bg",
      "quantity": 2,
      "itemPrice": 12.34
    }
  ]
}

Покупка

Отправляйте событие один раз после подтверждения заказа. cart должен содержать оплаченные позиции, а не состояние пользовательской корзины после её очистки.

{
  "type": "purchase-v1",
  "name": "Purchase",
  "uniqueTransactionId": "order-100500",
  "value": 90.55,
  "currency": "RUB",
  "cart": [
    {
      "productId": "item-34454",
      "quantity": 1,
      "itemPrice": 65.87
    },
    {
      "productId": "sku-4324-bg",
      "quantity": 2,
      "itemPrice": 12.34
    }
  ],
  "customProps": {
    "paymentMethod": "card"
  }
}

Удаление из корзины

quantity и value описывают удалённые единицы, а cart — состояние корзины после удаления.

{
  "type": "remove-from-cart-v1",
  "name": "Remove from Cart",
  "productId": "item-34454",
  "quantity": 1,
  "value": 59.13,
  "currency": "RUB",
  "cart": [
    {
      "productId": "item-34454",
      "quantity": 1,
      "itemPrice": 59.13
    }
  ]
}

Для полной очистки, объединения корзин или другого пакетного изменения используйте sync-cart-v1.

Синхронизация корзины

Событие передаёт снимок состояния корзины после восстановления, объединения, серверной корректировки или массового удаления.

{
  "type": "sync-cart-v1",
  "name": "Sync Cart",
  "currency": "RUB",
  "cart": [
    {
      "productId": "sku-4324-bg",
      "quantity": 2,
      "itemPrice": 12.34
    }
  ]
}

Добавление в избранное

{
  "type": "add-to-wishlist-v1",
  "name": "Add to Wishlist",
  "productId": "item-34454",
  "customProps": {
    "size": "M"
  }
}

Смена атрибута товара

Параметры стандартного события, которых нет среди верхнеуровневых полей API V2, передаются в customProps.

{
  "type": "change-attr-v1",
  "name": "Change Attribute",
  "customProps": {
    "attributeType": "color",
    "attributeValue": "navy_blue"
  }
}

Фильтрация товаров

{
  "type": "filter-items-v1",
  "name": "Filter Items",
  "customProps": {
    "filterType": "price",
    "filterNumericValue": "5000"
  }
}

Передавайте ровно одно из полей filterNumericValue и filterStringValue.

Поиск

{
  "type": "keyword-search-v1",
  "name": "Keyword Search",
  "customProps": {
    "keywords": "беспроводные наушники"
  }
}

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

Ввод промокода

{
  "type": "enter-promo-code-v1",
  "name": "Promo Code Entered",
  "customProps": {
    "code": "SALE10"
  }
}

Сортировка товаров

{
  "type": "sort-items-v1",
  "name": "Sort Items",
  "customProps": {
    "sortBy": "price",
    "sortOrder": "ASC"
  }
}

Подписка на рассылку

Отправляйте событие после подтверждённой подписки. Идентификаторы в нём не заменяют Login или Signup для склейки профиля.

{
  "type": "newsletter-subscription-v1",
  "name": "Subscription",
  "hashedEmail": "SHA256_LOWERCASE_EMAIL"
}

Регистрация

{
  "type": "signup-v1",
  "name": "Signup",
  "cuid": "HASHED_PHONE_STRING",
  "cuidType": "phone_hash"
}

Вход

{
  "type": "login-v1",
  "name": "Login",
  "cuid": "HASHED_PHONE_STRING",
  "cuidType": "phone_hash"
}

Для Signup и Login используется одинаковый набор идентификационных полей:

Идентификация через CUID

Для объединения профилей между Web, мобильными SDK, API V2 и офлайн-данными используйте один и тот же cuid:

1. Удалите из номера телефона все символы, кроме цифр.
2. Для РФ и КЗ приведите номер к формату 7XXXXXXXXXX. Для других стран используйте международный формат без + и разделителей.
3. Рассчитайте SHA-256 по нормализованной UTF-8 строке.
4. Передайте результат как шестнадцатеричную строку в нижнем регистре и укажите cuidType: "phone_hash".

Если используется hashedEmail, сначала приведите email к нижнему регистру, затем вычислите SHA-256. В одном событии V2 нельзя одновременно передавать cuid и hashedEmail.

Одинаковая функция нормализации и хеширования должна использоваться в клиентской и серверной части, а также в ETL-процессах. Если CDP или DWH уже рассчитывает cuid, используйте именно этот хеш во всех каналах.

📖 Подробнее о формате cuid и cuidType при импорте транзакций: Импорт транзакций

Кастомные события

Для нестандартного действия задайте стабильные type и name. Дополнительные параметры передавайте в customProps; ключи и значения должны быть строками.

{
  "type": "survey-completed-v1",
  "name": "Survey Completed",
  "value": 100,
  "eventTime": "2025-12-31T15:16:17+03:00",
  "customProps": {
    "surveyId": "summer-2025-feedback",
    "rating": "5"
  }
}