Metrica

Ecommerce

Tip. Working with the JavaScript API requires knowledge of HTML and JavaScript. If you don't have these skills, contact your website developer or webmaster.

Yandex.Metrica offers features for collecting and analyzing ecommerce data.

Attention! Previously, order parameters were transmitted using a pre-defined set of session parameters. This method is now outdated. It is still supported for backward compatibility, but we don't recommend its use. The Ecommerce component of Yandex.Metrica allows you to track more data and provides more sophisticated analysis tools.

Enabling Ecommerce

To connect Ecommerce:

  1. In the Settings section, go to the Counter code tab and enable the option Dispatch ecommerce data to Metrica. A container for collecting data from dataLayer will be added to the counter code by default.

  2. Embed (or update) the counter code on all the site pages that contain information about products and orders (item details, the “Add to basket” button, and so on).
  3. Put the dataLayer container on the site pages and configure sending events involving products to Yandex.Metrica.

Data representation and transfer

In Ecommerce, every product item is an object that certain actions can be performed on, such as viewing the complete item description or adding it to the basket. This data is transmitted as JavaScript objects containing the action ID and a list of descriptions of items that this action was performed on. In the context of the JavaScript API, we call these objects Ecommerce objects.

To pass data in the form of Ecommerce objects to the Yandex.Metrica service, you need to put them in a special JavaScript array using the push method. We call this array the data container.

The data container must be located in the global namespace, and its name must match the name specified during counter configuration or initialization. If the data container is named dataLayer, or the Yandex.Metrica counter was initiated with the ecommerce parameter set to true, it is assumed that the data container is the window.dataLayer array.

<script type="text-javascript">
window.dataLayer = window.dataLayer || [];
</script>
...
<script type="text/javascript">
window.dataLayer.push ({...});
</script>

The name of the data container and the structure of the Ecommerce objects in it correspond to the same entities in Google Analytics Enhanced Ecommerce. This means that if you have already set up transmitting data to Google Analytics Enhanced Ecommerce and enabled Ecommerce in Yandex.Metrica, the latter will start collecting data the same way.

An Ecommerce object has the following format:

window.dataLayer.push({
    "ecommerce
[no-highlight[

Object

Required container field

]no-highlight]
": { "currencyCode
[no-highlight[

String

Three-letter ISO 4217 currency code.

Supported currencies
  • EUR — Euro
  • USD — United States dollar
  • GBP — British pound
  • CAD — Canadian dollar
  • AUD — Australian dollar
  • RUB — Russian ruble
  • UAH — Ukrainian hryvnia
  • BYN — Belarusian ruble
  • TRY — Turkish lira
  • CNY — Chinese yuan
  • KZT — Kazakhstani tenge
  • TMT — Turkmenistan manat
  • LVL — Latvian lats
  • MDL — Moldavan leu
  • CHF — Swiss franc
  • THB — Thai baht
  • YND — Yandex units

If a different currency is passed, null values will be sent instead of currencies and amounts.

]no-highlight]
": "RUB", "<actionType>
[no-highlight[

The field name (substituted in place of <actionType>) is the identifier of an action performed with a set of products.

Possible values:

  • detail — Viewing the full item description (product profile).
  • add — Adding the item to the basket.
  • remove — Removing the item from the basket.
  • purchase — Purchasing.
]no-highlight]
" : { "actionField
[no-highlight[

Object

Object of the <actionField> type. Additional data describing the action performed.

Processed only if the action is a purchase (<actionType> — purchase)

]no-highlight]
" : <actionField>, "products
[no-highlight[

Array

List of descriptions of items that the specified action was performed on. Item descriptions are <productFieldObject> objects.

]no-highlight]
" : [<productFieldObject>, <productFieldObject>, ...] } } });
FieldTypeDescription
ecommerce *

Object

Required container field

currencyCode

String

Three-letter ISO 4217 currency code.

Supported currencies
  • EUR — Euro
  • USD — United States dollar
  • GBP — British pound
  • CAD — Canadian dollar
  • AUD — Australian dollar
  • RUB — Russian ruble
  • UAH — Ukrainian hryvnia
  • BYN — Belarusian ruble
  • TRY — Turkish lira
  • CNY — Chinese yuan
  • KZT — Kazakhstani tenge
  • TMT — Turkmenistan manat
  • LVL — Latvian lats
  • MDL — Moldavan leu
  • CHF — Swiss franc
  • THB — Thai baht
  • YND — Yandex units

If a different currency is passed, null values will be sent instead of currencies and amounts.

<actionType> *

The field name (substituted in place of <actionType>) is the identifier of an action performed with a set of products.

Possible values:

  • detail — Viewing the full item description (product profile).
  • add — Adding the item to the basket.
  • remove — Removing the item from the basket.
  • purchase — Purchasing.
actionField

Object

Object of the <actionField> type. Additional data describing the action performed.

Processed only if the action is a purchase (<actionType> — purchase)

products *

Array

List of descriptions of items that the specified action was performed on. Item descriptions are <productFieldObject> objects.

* Required parameter.

Item data

An object describing a particular item.

The structure of the object describing the item is denoted as <productFieldObject>.

Table 1. Object field

FieldTypeDescription
id *
[no-highlight[

You must specify either “name“ or “id“

]no-highlight]

String

Item ID. For example, the SKU.

You must specify either "name" or "id"

name *
[no-highlight[

You must specify either “name“ or “id“

]no-highlight]

String

Name of the product. For example, "T-shirt"

You must specify either "name" or "id"

brand

String

The brand or trademark associated with the item. For example, "Yandex"

category

String

The category the item belongs to.

The hierarchy of categories supports up to 4 levels. Use the / symbol to separate levels. For example, "Clothing/Men's clothing/T-shirts"

coupon

String

A promo code associated with the item. For example, "PARTNER_SITE_15"

position

Number

The position of the item in the list. For example, 2

price

Number

Price of a product unit

quantity

Integer

Quantity of product units

variant

String

A variation of the item. For example, "Red"

Action data

An object containing data about an action performed with an item or set of products.

Processed only if the action is a purchase (<actionType> — purchase).

The structure of the object describing the action is denoted as <actionField>.

Table 2. Object field

FieldTypeDescription
id *
[no-highlight[

Required information.

]no-highlight]

String

Purchase ID.

Required information.

Example: TRX#54321

coupon

String

A promo code associated with the entire purchase

goal_id

String

Numeric ID of the goal (goal ID). Specified if this action was the goal.

The goal must be set as a JavaScript event type

How can I get the ID of a goal?
revenue

Number

The revenue received.

If omitted, it is calculated automatically as the sum of the prices of all the items associated with the purchase.

Examples

All the examples assume that the counter was initialized with Ecommerce enabled, and data is transferred via the window.dataLayer container.

Viewing the full item description

dataLayer.push({
    "ecommerce": {
        "detail": {
            "products": [
                {
                    "id": "P15432",
                    "name" : "T-shirt",
                    "price": 477.60,
                    "brand": "Yandex",
                    "category": "Clothing/Men's clothing/T-shirts",
                    "variant" : "Red"
                },
                {
                    "name": "Ya logo",
                    "price": 50,
                }
            ]
        }
    }
});

Adding an item to the basket

dataLayer.push({
    "ecommerce": {
        "add": {
            "products": [
                {
                    "id": "43521",
                    "name": "Yandex bag",
                    "price": 654.32,
                    "brand": "Yandex",
                    "category": "Accessories/Handbags",
                    "quantity": 2
                }
            ]
        }
    }
});

Removing an item from the basket

dataLayer.push({
    "ecommerce": {
        "remove": {
            "products": [
                {
                    "id": "15243",
                    "name": "Set of Yandex cleaning cloths for phone screens",
                    "category": "Mobile phone accessories"
                }
            ]
        }
    }
});

Purchase

dataLayer.push({
    "ecommerce": {
        "purchase": {
            "actionField": {
                "id" : "TRX987",
                "goal_id" : "1234567"
            },
            "products": [
                {
                    "id": "25341",
                    "name": "Yandex men's sweatshirt",
                    "price": 1345.26,
                    "brand": "Yandex",
                    "category": "Clothing/Men's clothing/Sweatshirts and hoodies",
                    "variant": "Orange"
                },
                {
                    "id": "25314",
                    "name": "Yandex women's sweatshirt",
                    "price": 1543.62,
                    "brand": "Yandex",
                    "category": "Clothing/Women's clothing/Sweatshirts and hoodies",
                    "variant": "White",
                    "quantity": 3
                }
            ]
        }
    }
});