# Настройка передачи событий

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

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

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:

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:

GF.API("event", {
  name: "Remove from Cart",
  properties: {
    eventType: "remove-from-cart-v1",
    value: 34.45,
    currency: "any supported currency code",
    productId: "gswefd-34-454",
    quantity: 1,
    cart: [{
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34
      },
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 34.45
      }
    ]
  }
});

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

Данное событие обновляет текущее состояние корзины. Событие рекомендуется к использованию в случае пакетного изменения состава корзины или изменения сотава корзины без участия пользователя, например:

1. Обновление корзины сервером (например, автоудаление из корзины товаров, которые закончились в процессе сессии пользователя)
2. Обновление корзины при авторизации пользователя (объединение корзин до/после логина)
3. Обновление корзины при заходе пользователя на сайт, в том числе автологин (например, автоматическая подгрузка корзины, собранной на mobile при заходе в web)
4. Массовое единовременное удаление товаров из корзины - полная очистка корзины или удаление ряда позиций одним кликом

GF.API("event", {
  name: "Sync cart",
  properties: {
    eventType: "sync-cart-v1",
    currency: "any supported currency code", 
    cart: [ 
      {
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34
      },
      {
        productId: "item-34454",
        quantity: 1,
        itemPrice: 34.45
      }
    ]
  }
});

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

GF.API("event", {
  name: "Add to Wishlist",
  properties: {
    eventType: "add-to-wishlist-v1",
    productId: "item-34454"
  }
});

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

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

GF.API("event", {
  name: "Change Attribute",
  properties: {
    eventType: "change-attr-v1",
    attributeType: "Color",
    attributeValue: "Navy Blue"
  }
});

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

Используется, когда пользователь фильтрует товары по какому-либо значению поля.

GF.API("event", {
  name: "Filter Items",
  properties: {
    eventType: "filter-items-v1",
    filterType: "Color", // Name of filter (Color, Size, Brand, Fit, Author, Keyword, Category...)
    filterNumericValue: 4
  }
});

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

GF.API("event", {
  name: "Keyword Search",
  properties: {
    eventType: "keyword-search-v1",
    keywords: "my search string"
  }
});

GF.API("event", {
  name: "Promo Code Entered",
  properties: {
    eventType: "enter-promo-code-v1",
    code: "..."
  }
});

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

GF.API("event", {
  name: "Sort Items",
  properties: {
    eventType: "sort-items-v1",
    sortBy: "price",
    sortOrder: "ASC"
  }
});

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

GF.API("event", {
  name: "Subscription",
  properties: {
    eventType: "newsletter-subscription-v1",
    hashedEmail: "хешированный ранее адрес",   }
});
// и/или; данные методы могут быть использованы параллельно
GF.API("event", {
  name: "Subscription",
  properties: {
    eventType: "newsletter-subscription-v1",
    cuid: "...", 
    cuidType: "..." 
  }
});

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

сuid может означать один из заранее заданных типов идентификаторов (допустимые и предопределённые типы - справочник) или иметь значение не из справочника, если на стороне клиента есть свой внутренний идентификатор, например, CRM_ID, мобильный телефон и другие.

GF.API("event", {
  name: "Signup",
  properties: {
    eventType: "signup-v1",
    hashedEmail: "хешированный ранее адрес",   }
});
// и/или; данные методы могут быть использованы параллельно
GF.API("event", {
  name: "Signup",
  properties: {
    eventType: "signup-v1",
    cuid: "...", 
    cuidType: "..." 
  }
});

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

сuid может означать один из заранее заданных типов идентификаторов (допустимые и предопределённые типы - справочник) или иметь значение не из справочника, если на стороне клиента есть свой внутренний идентификатор, например, CRM_ID, мобильный телефон и другие.

GF.API("event", {
  name: "Login",
  properties: {
    eventType: "login-v1",
    // 1. Нормализуйте номер телефона:
    //    "+7 (999) 000-00-00" → "79990000000"
    //    или международный формат без "+" и разделителей
    // 2. Постройте SHA-256 хеш нормализованной строки (UTF-8, lowercase hex)
    cuid: "HASHED_PHONE_STRING", // SHA-256(нормализованный телефон)
    cuidType: "phone_hash"
  }
});

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

сuid может означать один из заранее заданных типов идентификаторов (допустимые и предопределённые типы - справочник) или иметь значение не из справочника, если на стороне клиента есть свой внутренний идентификатор, например, CRM_ID, мобильный телефон и другие.

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

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

или

GF.API("event", {
  name: "EVENT_NAME"
})

Происходит двумя основными способами.

Стандартный способ (рекомендуется): через cuid на основе номера телефона

• В событии Login в properties.cuid обязательно передаётся SHA-256 хеш (lowercase hex) нормализованного мобильного телефона.
• Номер телефона перед хешированием должен быть очищен от всех символов, кроме цифр:
  • для РФ/КЗ — формат 7XXXXXXXXXX (начинается с кода страны 7, без +, пробелов, скобок и тире);
  • для других стран — международный формат без + и разделителей.
• В properties.cuidType обязательно передаётся строка phone_hash.
• Тот же хеш и значение cuidType = phone_hash должны использоваться во всех каналах (Web, мобильные SDK, Server-Side API, импорт офлайн-данных), чтобы профили объединялись в единую сущность.
• Если в CDP или DWH уже рассчитывается этот идентификатор по описанному алгоритму, во всех типах интеграции (включая Web и мобильные SDK) необходимо передавать именно тот хеш, который используется в CDP, чтобы обеспечить единый «золотой» ключ пользователя.

С помощью поля hashedEmail

В нем передается SHA-256 хеш email пользователя. Если передается email, то адрес переводится в lowercase, затем хешируется. Пример:

Test@TEST.com → test@test.com — перевод в lowercase
test@test.com → f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a — хеширование

Поле hashedEmail может использоваться для сценариев, где идентификация строится по email (например, подписка на рассылку), но при стандарте по телефону оно не должно рассматриваться как основной CUID.

С помощью поля cuid (произвольные идентификаторы)

cuid (Customer Unique Identifier) может быть любым уникальным значением, используемым для идентификации пользователя — это может быть CRM ID или любой другой ID. При выбранном стандарте по телефону значение cuid в событии Login всегда должно быть хешем телефона с типом phone_hash.