Session parameters

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.

The majority of session data is collected automatically by your Yandex.Metrica tag. However, you'll likely find that it would benefit you to supplement this data with your own data. For example, you may be interested in statistics on what specific items were purchased or what actions users who were logged in performed.

Yandex.Metrica lets you connect a custom data set to the corresponding session. These sets are called session parameters. This data can be shown in reports, or used in conditions for dimensions and segmentation.

  1. Transmitting data
  2. Processing transmitted data
  3. Examples of transmitting parameters

Transmitting data

Session parameters are transmitted to the tag storage using the JavaScript API. Data can be sent either during tag initialization, or at any time before the session timeout expires.

During tag initialization, session parameters are specified in the params parameter.

To send session parameters during site user sessions, use the params method, or the optional argument for the extLink, file, hit, or reachGoal methods.

Session parameters are transmitted as a JavaScript object or an array.

Attention. Some of the field names are reserved for transmitting e-commerce data. Do not use these names to send session parameters. Do not send your custom parameters with reserved ones.

Up to 1000 parameters can be transmitted in a single session. When the hierarchical data structure is transmitted, the Yandex.Metrica reports will display up to 10 nesting levels.

window.yaParams = {
    x: 10,
    y: "unauthorized user"
}

ym(XXXXXX, 'params', window.yaParams||{});

Processing transmitted data

Data that is transmitted to Yandex.Metrica as JavaScript objects are processed as follows.

The field name and nesting level are interpreted as the parameter name and level, respectively. The field value is processed as follows, depending on its type:

  • object — A tree branch is created for each object key, and the algorithm is called recursively for each value.
  • string — Counts the number of times each different value of the string occurs.
  • number — Calculates the total and average value of all numbers.
  • array — Creates a [Parameters] tree branch, calculates the number of times the value is an array, and invokes the algorithm recursively for each item in the array.
  • true, false or null — Calculates the number of times each value occurs.

Parameters are transmitted to Yandex.Metrica as dimensions. The numbers that are calculated by processing the data are the metrics. To see the statistics for the transmitted session parameters, use the Session Parameters report.

Examples of transmitting parameters

Transmitting a hierarchical data structure

For instance, we need to transmit data and show it in a report in a tree view.

window.yaParams = {
    "level1":{"level2":["level3_1","level3_2"]}}
...
ym(XXXXXX, 'params', window.yaParams||{});
AB testing

Let’s say we need to conduct an experiment to determine how the color of the Buy button affects the conversion rate for a “View basket” goal.

If the user is shown a red button, we use the following parameter:

window.yaParams = {ab_test: "red button"};

If the user is shown a green button, we use the following parameter:

window.yaParams = {ab_test: "green button"};

This parameter is transmitted in any convenient way. For example, it can be passed when initializing the tag on product pages or using the reachGoal method that is called when the Buy button is clicked.

After this, we will be able to use the ab_test parameter value in the Yandex.Metrica interface for selecting the corresponding data.

Report on authorized and unauthorized users

Use the following code sample to analyze differences in the behavior of registered and non-registered site users:

<script type="text/javascript">
window.yaParams = {'Login': '[% insert the user's login name from the site's template engine %]' || 'Guest'};
ym(XXXXXX, 'params', window.yaParams||{});
</script>

where XXXXXX is the tag ID.