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

События (ивенты) нужны для отслеживания важных пользовательских действий, таких как добавление товара в корзину, добавление в список желаемого, аутентификации в личном кабинете и многие другие. Отслеживание таких событий необходимо для понимания поведения пользователя и таргетинга на его основе, а также корректного измерения эффективности рекламных кампаний.

Для отправки данных в GF необходимо внедрить небольшой кусочек кода для каждого необходимого события. В событии вы можете передавать тот набор параметров, которые в дальнейшем планируете использовать для работы. Ряд событий, таких как покупка или вход в личный кабинет требуют внедрения по определенной схеме, вместе с тем, для других целевых действий вы можете создавать и собственные события.

Для e-commerce события Purchase и Add to Cart являются обязательными, но мы также рекомендуем внедрить максимальное количество событий из списка преднастроенных, которые релевантны для вашего сайта. Это поможет реализовать больше use-кейсов и расширить профиль пользователя. Окончательный список требуемых событий согласовывается с вашим менеджером по персонализации в зависимости от планируемых use-кейсов.

Основные преднастроенные события

Добавление в корзину (обязательно для e-commerce)

Пример вызова:

Javascript

GF.API("event", {
  name: "Add to Cart",
  properties: {
    eventType: "add-to-cart-v1",
    value: 118.26,
    currency: "any supported currency code",
    productId: "item-34454",
    quantity: 2,
    cart: [{
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      },
      {
        productId: "item-34454",
        quantity: 2,
        itemPrice: 59.13
      }
    ]
  }
});

Описание полей объекта properties:

Свойство	Описание	Тип
eventType*	Должен быть "add-to-cart-v1"	string
value*	Сумма добавляемого в корзину. Если добавляется больше одной единицы товара, то содержит количество умноженное на стоимость единицы. Например, для 99 рублей 99 копеек передается как 99.99	float
currency	Код валюты ISO 421, например "RUB". Опционально, но необходимо для сайтов с поддержкой мультивалютности	string
productId*	SKU, указанный так же, как и в фиде	string
quantity*	Количество товаров, добавленных в корзину	integer, только положительные значения
cart	Текущее состояние корзины, включая последний добавленный товар. Товар должны идти в порядке добавления - от самых старых до самых новых	array
Объект товара:
productId*	SKU, указанный так же, как и в фиде	string
quantity*	Количество единиц данного товара в корзине	integer, только положительные значения
itemPrice*	Стоимость одной единицы товара после применения скидок (при их наличии)	float

Частые ошибки:

1. В событии `Add to cart` часто некорректно передается параметр `quantity` . Данный параметр должен отражать фактически добавленное число единиц товара, а не сумму всех единиц после действия. Пример: в корзине было 2 единицы товара и мы добавили еще 1. В событии мы ожидаем увидеть `quantity: 1`, а видим `quantity: 3` — это неправильно.

Покупка (обязательно для e-commerce)

Пример вызова:

Javascript

GF.API("event", {
  name: "Purchase",
  properties: {
    uniqueTransactionId: "123456",
    eventType: "purchase-v1",
    value: 90.55,
    currency: "any supported currency code",
    cart: [
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 65.87,
      }, {
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      }
    ]
  }
});

Описание полей объекта properties:

Свойство	Описание	Тип
eventType*	Должен быть "purchase-v1"	string
uniqueTransactionId	Уникальный ID транзакции. Гарантирует, что к одной транзакции относится только одна покупка. Максимум 64 символа	string
value*	Совокупная денежная стоимость события. Например, для 99 рублей 99 копеек передается как 99.99	float
currency	Код валюты ISO 421, например "RUB". Опционально, но необходимо для сайтов с поддержкой мультивалютности	string
cart*	Товары должны идти в порядке добавления - от самых старых до самых новых
Объект товара:
productId*	SKU, указанный так же, как и в фиде	string
quantity*	Количество единиц данного товара в корзине	integer, только положительные значения
itemPrice*	Стоимость одной единицы товара после применения скидок (при их наличии)	float

Регистрация

Пример вызова:

Javascript

GF.API("event", {
  name: "Signup",
  properties: {
    eventType: "signup-v1",
    hashedEmail: "хешированный ранее адрес",   }
});

Описание полей объекта properties:

Свойство	Описание	Тип
eventType*	Должен быть "signup-v1"	string
hashedEmail*	Email или номер телефона, переведенный в lowercase и хешированный на стороне клиента в формате MD5	string

Логин

Пример вызова:

Javascript

GF.API("event", {
  name: "Login",
  properties: {
    eventType: "login-v1",
    hashedEmail: "хешированный ранее адрес"
	}
});

Описание полей объекта properties:

Свойство	Описание	Тип
eventType*	Должен быть "login-v1"	string
hashedEmail*	Email, переведенный в lowercase и хешированный на стороне клиента в формате MD5	string

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

Происходит с помощью поля hashedEmail. В нем передается md5-хеш email или телефона пользователя.

1. Если передается email, то адрес переводится в lowercase, затем хешируется. Пример:

   [e-mail] → [e-mail] - перевод в lowercase

   [e-mail] → b642b4217b34b1e8d3bd915fc65c4452 - хеширование

2. Если передается номер телефона, то приводится к виду

   7XXXXXXXXXX (начинается с кода страны 7, без плюса в начала, без скобок, тире и т.д)

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

Если вы хотите отслеживать событие, не указанное в списке выше, воспользуйтесь для его создания следующей структурой:

GF.API("event", {
  name: "EVENT_NAME",
  properties: {  
    [FIRST PROPERTY NAME]: "[PROPERTY VALUE]",  // Optional
    [SECOND PROPERTY NAME]: "[PROPERTY VALUE]",  // Optional
    value: "[MONETARY VALUE]" // Optional
  }
})