Электронная коммерция для Android

Краткое содержание

Доступные шаблоны событий
Статья описывает два шаблона для интеграции событий электронной коммерции:

EcommerceGA4Event — для событий в формате GA4.
EcommerceUAEvent — для событий в формате Universal Analytics.

Шаблон EcommerceGA4Event
Для использования шаблона:

Выберите тип события через EcommerceGA4Name.
Заполните поля EcommerceGA4, включая transactionId, value, currency и массив EcommerceGA4Item.
В статье приведена структура классов и пример заполнения события.

Шаблон EcommerceUAEvent
Для использования шаблона:

Выберите тип события через EcommerceUAName.
Укажите currencyCode и заполните соответствующие поля (например, add, purchase, checkout).
В статье описаны структуры ActionField, Product, Promotion и пример события.

Отправка событий
В статье приведена пошаговая инструкция по отправке событий:

Создайте экземпляр события, унаследованный от Event.
Используйте MtsAnalyticsApi для отправки события через метод track().

Если вы хотите получать информацию о том, как посетители взаимодействуют с вашими товарами или услугами, вам необходимо настроить отправку событий электронной коммерции. После завершения настройки информация о событиях начнёт поступать в Аналитику и отображаться в отчётах.

Доступные шаблоны событий

Чтобы сделать интеграцию с Аналитикой быстрее и проще, мы подготовили шаблоны, которые вы могли использовать, если передавали данные в GA4 или в Universal Analytics:

EcommerceGA4Event — подходит, если вы размечали события в формате GA4
EcommerceUAEvent — подходит, если вы размечали события в формате Universal Analytics

Шаблон EcommerceGA4Event

Разным действиям пользователей соответствуют разные типы событий:

Выберите тип события с помощью EcommerceGA4Name
Заполните необходимые поля EcommerceGA4

EcommerceGA4Event(
    val eventName: EcommerceGA4Name,
    val ecommerceGA4: EcommerceGA4,
    val customParameters: HashMap<String, Any?>? = null
)
EcommerceGA4(
    val transactionId: String? = null,
    val affiliation: String? = null,
    val value: String? = null,
    val currency: String? = null,
    val tax: String? = null,
    val shipping: String? = null,
    val shippingTier: String? = null,
    val paymentType: String? = null,
    val coupon: String? = null,
    val itemListName: String? = null,
    val itemListId: String? = null,
    var creativeName: String? = null,
    var creativeSlot: String? = null,
    var promotionId: String? = null,
    var promotionName: String? = null,
    var parameters: HashMap<String, Any?>? = null,
    var items: List<EcommerceGA4Item> = mutableListOf()
)

Доступные опции EcommerceGA4Name:

Опция	Описание	Обязательные поля
add_payment_info	Пользователь выбрал способ оплаты	Массив EcommerceGA4Item
add_shipping_info	Пользователь выбрал способ доставки	Массив EcommerceGA4Item
add_to_cart	Пользователь добавляет товар в корзину из карточки товара или любых других товарных блоков	Массив EcommerceGA4Item
add_to_wishlist	Пользователь добавляет товар в избранное	Массив EcommerceGA4Item
begin_checkout	Пользователь переходит на страницу оформления заказа	Массив EcommerceGA4Item
purchase	Пользователь совершил покупку. Такое событие должно срабатывать только один раз для оформленного заказа.	Массив EcommerceGA4Item
refund	Пользователь возвращает покупку	При полном возврате — transactionId. При частичном возврате — массив EcommerceGA4Item
remove_from_cart	Пользователь удаляет товар из корзины	Массив EcommerceGA4Item
select_item	Пользователь кликает по товарам в каталоге, в выдаче поиска, в товарных блоках и других списках	Массив EcommerceGA4Item
select_promotion	Пользователь кликает на рекламные кампании	Массив EcommerceGA4Item
view_cart	Пользователь просматривает корзину	Массив EcommerceGA4Item
view_item	Пользователь просматривает карточку товара	Массив EcommerceGA4Item
view_item_list	Пользователь просматривает список товаров	Массив EcommerceGA4Item
view_promotion	Пользователь просматривает рекламные кампании на странице	Массив EcommerceGA4Item

EcommerceGA4Item

К событию разметки можно добавить описание списка товаров или услуг:

EcommerceGA4Item(
    val itemId: String,
    val itemName: String,
    val itemListName: String? = null,
    val itemListId: String? = null,
    val index: String? = null,
    val itemBrand: String? = null,
    val itemCategory: String? = null,
    val itemCategory2: String? = null,
    val itemCategory3: String? = null,
    val itemCategory4: String? = null,
    val itemCategory5: String? = null,
    val itemVariant: String? = null,
    val affiliation: String? = null,
    val discount: String? = null,
    val coupon: String? = null,
    val price: String? = null,
    val currency: String? = null,
    val quantity: String? = null,
    var locationId: String? = null,
    var creativeName: String? = null,
    var creativeSlot: String? = null,
    var promotionId: String? = null,
    var promotionName: String? = null,
    var parameters: HashMap<String, Any?>? = null
)

Пример структуры заполненного события

{
  "event": "enum_event_name",
  "ecommerce": {
    "transaction_id": "123456",
    "affiliation": "Online Store",
    "value": "99.99",
    "currency": "USD",
    "tax": "8.25",
    "shipping": "5.00",
    "shipping_tier": "Ground",
    "payment_type": "Credit Card",
    "coupon": "SUMMER2024",
    "item_list_name": "Best Sellers",
    "item_list_id": "best_sellers_001",
    "custom_param_1_new": "value1",
    "custom_param_2_new": "value2",
    "items": [
      {
        "id": "SKU1234",
        "name": "T-Shirt",
        "list_name": "Summer Collection",
        "list_id": "summer_2024",
        "index": "1",
        "brand": "BrandName",
        "category": "Clothing",
        "category2": "Men",
        "category3": "Tops",
        "category4": "T-Shirts",
        "category5": "Short Sleeve",
        "variant": "Blue",
        "affiliation": "Online Store",
        "discount": "10.00",
        "coupon": "SUMMER2024",
        "price": "19.99",
        "currency": "USD",
        "quantity": "2",
        "custom_param_3_new": "value3",
        "custom_param_4_new": "value4"
      }
    ]
  }
}

Шаблон EcommerceUAEvent

Разным действиям пользователей соответствуют разные типы событий:

Выберите тип события с помощью EcommerceUAName
В EcommerceUAукажите код валюты currencyCode и добавьте подходящее действие пользователя. Например, currencyCode = "RUB", для eventName = EcommerceUAName.Add заполните EcommerceUA.add

EcommerceUAEvent(
    val eventName: EcommerceUAName,
    val ecommerceUA: EcommerceUA,
    val ecommerceParameters: HashMap<String, Any?>? = null,
    val customParameters: HashMap<String, Any?>? = null
)
class EcommerceUA(
    val currencyCode: String? = null,
    val purchase: Purchase? = null,
    val checkoutOption: CheckoutOption? = null,
    val checkout: Checkout? = null,
    val add: Add? = null,
    val refund: Refund? = null,
    val remove: Remove? = null,
    val detail: Detail? = null,
    val click: Click? = null,
    val promoClick: PromoClick? = null,
    val promoView: PromoView? = null,
    val impressions: Impressions? = null
)

Доступные опции EcommerceUAName:

Опция	Описание	Обязательные поля
checkout_option	Пользователь выбрал способ оплаты или доставки	ActionField в CheckoutOption
add	Пользователь добавляет товар в корзину из карточки товара или любых других товарных блоков	Массив Product в Add. В каждом Product заполнены поля name и id
checkout	Пользователь переходит на страницу оформления заказа	Массив Product в Checkout. В каждом Product заполнены поля name и id
purchase	Пользователь добавляет товар в корзину из карточки товара или любых других товарных блоков	ActionField в Purchase, поля id и revenue. Массив Product в Purchase, поля name и id
refund	Пользователь возвращает покупку	ActionField в Refund. При полном возврате — поле id, при частичном — поля id и quantity в Product
remove	Пользователь удаляет товар из корзины	Массив Product в Remove. В каждом Product — поля name и id
click	Пользователь кликает по товарам в каталоге, в выдаче поиска, в товарных блоках и в других списках	Массив Product в Click. В каждом Product — поля name и id
promoClick	Пользователь кликает на рекламные кампании	Массив Promotions в PromoClick
detail	Пользователь просматривает карточку товара	Массив Product в Product. В каждом Product — поля name и id
impressions	Пользователь просматривает список товаров	Поля name и id в Product
promoView	Пользователь просматривает рекламные кампании на странице	Массив Promotions в PromoView. В каждом Promotion — поля name и id

Структура ActionField

ActionField {
  "id": "id",                         // optional, идентификатор транзакции. Обязателен при заполнении структур Purchase и Refund
  "affiliation": "affiliation",       // optional, магазин или филиал, в котором была совершена транзакция
  "revenue": "revenue",               // optional, денежная ценность события в указанной валюте. Обязателен при заполнении Purchase структуры
  "tax": "tax",                       // optional, сумма налога
  "shipping": "shipping",             // optional, стоимость доставки
  "coupon": "coupon",                 // optional, код купона
  "quantity": "quantity",             // optional, количество единиц товара
  "step": "step",                     // optional, шаг воронки ecom
  "option": "option",                 // optional, выбранный способ оплаты
  "list": "list",                     // optional, название списка, в который входит товар
  "custom_param_1": "value1",         // optional
  "custom_param_2": "value2"          // optional
}

Структура Product

Product {
  "id": "id",                         // required, идентификатор или код товара (SKU)
  "name": "name",                     // required, название товара
  "price": "price",                   // optional, цена товара
  "brand": "brand",                   // optional, бренд, к которому относится товар
  "category": "category",             // optional, категория, к которой относится товар
  "variant": "variant",               // optional, вариант товара
  "quantity": "quantity",             // optional, количество единиц товара
  "coupon": "coupon",                 // optional, код купона
  "list": "list",                     // optional, название списка, в который входит товар
  "position": "position",             // optional, позиция товара в списке
  "custom_param_1": "value1",         // optional
  "custom_param_2": "value2"          // optional
}

Структура Promotion

Promotion {
  "id": "id",                         // required
  "name": "name",                     // required
  "creative": "creative",             // optional
  "position": "position",             // optional
}

Пример структуры заполненного события

{
  "event": "enum_event_name",                 // required
  "custom_param_1": "value1",                 // optional
  "custom_param_2": "value2",                 // optional
  "ecommerce": {                              // required
    "currencyCode": "ru_rubl_123",            // optional
    "purchase": {                             // optional
      "actionField": ActionField,             // optional <out ActionField>
      "products": [                           // required <out List<Product>>
        {
          Product1,
          Product2
        }
      ]
    },
    "promoClick": {                           // optional
      "promotions": [                         // required <out List<Promotion>>
        {
          Promotion1,
          Promotion2
        }
      ]
    },
    // При наличии `impressions` также ожидается наличие транзакции `detail`
    "impressions": [                          // optional <out List<Product>>
      {
        Product1,
        Product2
      }
    ]
  }
}

ActionField {
  "id": "id",                         // optional
  "affiliation": "affiliation",       // optional
  "revenue": "revenue",               // optional
  "tax": "tax",                       // optional
  "shipping": "shipping",             // optional
  "coupon": "coupon",                 // optional
  "quantity": "quantity",             // optional
  "coupon": "coupon",                 // optional
  "step": "step",                     // optional
  "option": "option",                 // optional
  "list": "list",                     // optional
  "custom_param_1": "value1",         // optional
  "custom_param_2": "value2"          // optional
}

Product {
  "id": "id",                         // required
  "name": "name",                     // required
  "price": "price",                   // optional
  "brand": "brand",                   // optional
  "category": "category",             // optional
  "variant": "variant",               // optional
  "quantity": "quantity",             // optional
  "coupon": "coupon",                 // optional
  "list": "list",                     // optional
  "position": "position",             // optional
  "custom_param_1": "value1",         // optional
  "custom_param_2": "value2"          // optional
}

Promotion {
  "id": "id",                         // required
  "name": "name",                     // required
  "creative": "creative",             // optional
  "position": "position",             // optional
}

Отправка событий

Шаг 1. Создать экземпляр события

Для отправки создайте экземпляр события, унаследованного от:

val event: ru.mts.analytics.sdk2.publicapi.event.Event

Доступные типы событий:

Выберите в зависимости от шаблона разметки

val eCommerceEventGA4 = ru.mts.analytics.sdk2.publicapi.event.Event.EcommerceGA4Event(...)
val eCommerceEventUA = ru.mts.analytics.sdk2.publicapi.event.Event.EcommerceUAEvent(...)

Шаг 2. Отправлять события

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = config
)
mtsAnalytics.track(eCommerceEventUA) 
mtsAnalytics.track(eCommerceEventGA4) 

Доступные шаблоны событий​

Шаблон EcommerceGA4Event​

Шаблон EcommerceUAEvent​

Отправка событий​

Шаг 1. Создать экземпляр события​

Шаг 2. Отправлять события​