Передача событий

Чтобы собирать статистику и оптимизировать кампании, передавайте в Gravity Field информацию о действиях пользователя на сайте или в приложении.

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

curl --request POST \
  --url 'https://evs-01.gravityfield.ai/ssapi/event' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer your-api-key' \
  --data '
{
	"user": { 
		"id": "yaexono4ohphania" 
	},
	"session": { 
		"custom": "iquahngaishe2koh" 
	},
	"context": { 
		"page": {
			"type": "CART",
			"data": ["sku-4324-bg", "item-34454"],
			"location": "https://shop.ru/cart"
		},
		"device": {
			"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
			"ip": "54.100.200.255" 
		}
	},
	"events": [
	{
		"name": "Add to Cart",
		"properties": {
			"eventType": "add-to-cart-v1",
			"value": 118.26,
			"currency": "RUB",
			"productId": "item-34454",
			"quantity": 2,
			"cart": [
			{
        "productId": "sku-4324-bg",
        "quantity": 1,
        "itemPrice": 12.34
      },
      {
        "productId": "item-34454",
        "quantity": 2,
        "itemPrice": 59.13
      }
	    ]
		}
	}
	]
}'

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

Если Gravity Field создал нового пользователя или новую сессию, сохраните user.slid и session.sl из ответа и передавайте их в следующих запросах.

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

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

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

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

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

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

Покупка

Отправляйте событие один раз после подтверждения заказа. Корзина в событии покупки — это состав оплаченного заказа, а не состояние пользовательской корзины после её очистки.

{
  "name": "Purchase",
  "properties": {
    "eventType": "purchase-v1",
    "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
      }
    ]
  }
}

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

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

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

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

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

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

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

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

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

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

Используйте событие при выборе другого размера, цвета или иного товарного атрибута.

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

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

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

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

Поиск

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

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

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

{
  "name": "Promo Code Entered",
  "properties": {
    "eventType": "enter-promo-code-v1",
    "code": "SALE10"
  }
}

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

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

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

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

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

Регистрация

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

Вход

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

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

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

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

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

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

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

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

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

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

{
  "name": "Survey Completed",
  "properties": {
    "surveyId": "summer-2025-feedback",
    "rating": 5,
    "value": 100,
    "event_time": "2025-12-31T15:16:17+03:00"
  }
}