Установка Web SDK вручную

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

Шаг 1. Настроить код SDK
Код SDK включает скрипт для загрузки библиотеки и инициализации. Необходимо указать FLOW_ID, который можно получить через email. Имя переменной (ma) можно изменить.

Инициализация и конфигурация библиотеки
SDK инициализируется командой ma('create', config), где config — объект с настройками.

Свойства объекта config

id — обязательный параметр, идентификатор потока.
batching — объединение событий в один запрос. По умолчанию: 20 событий или 2 секунды.
ecommerce — включение слоя данных для событий электронной коммерции.
sendMethod — метод отправки данных: auto, beacon, xhr, double. По умолчанию: xhr.
outQueue — настройка очереди для сохранения событий при проблемах с сетью.
sendPageView — автоматическая отправка событий pageview. По умолчанию: true.
trackBounce — время для определения отказов. По умолчанию: 15 секунд.
plugins — список плагинов для расширения функционала.

Команды для настройки отправки событий
В статье описаны команды для отправки событий в MTC Аналитику.

Плагины для расширения функционала SDK
Доступны плагины: dataLayer, linker, performance, error. Их можно подключить после инициализации SDK.

Data Layer
Отслеживает события, добавленные в dataLayer. Инициализация: ma('addPlugin', 'dataLayer', <DATA_LAYER_NAME>).

Linker
Включает междоменное связывание сессий. По умолчанию отключен.

Performance
Собирает метрики производительности страниц. Инициализация: ma('addPlugin', 'performance').

Error
Отправляет ошибки JavaScript. Ручная отправка: ma('plugin', 'error', 'trackError', ...).

Шаг 2. Перенести код SDK на сайт
Скрипт SDK добавляется в HTML-код сайта, например, в раздел <head> или <body>. Пример конфигурации включает dataLayer и отключение pageview.

Для передачи данных о поведении пользователя в МТС Аналитику необходимо настроить поток данных через библиотеку SDK.

Важно

Вы не сможете обновлять код SDK только вручную, не через МТС Аналитику. Рекомендуем устанавливать библиотеку таким способом, если нет возможности использовать МТС Тег.

Как установить SDK через МТС Тег

Шаг 1. Настроить код SDK

Код библиотеки, в который при необходимости можно добавить плагины и конфигурации

<script>
  (function (sdk) {
    window[sdk] = window[sdk] || function () {
      (window[sdk].a = window[sdk].a || []).push(arguments);
    };
    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://static.a.mts.ru/web-sdk/analytics.js?name=' + sdk;
    document.head.appendChild(script);
  })('ma');
  ma('create', { id: '<FlOW_ID>' });
</script>

FLOW_ID — идентификатор потока. Если вы не получили ID потока, отправьте письмо на analytics.support@mts.ru с темой «Получение Flow ID». Идентификатор нужен для отправки данных с вашего ресурса в МТС Аналитику.
Имя переменной ma можно заменить на любое другое. Например, на mm

Инициализация и конфигурация библиотеки

При инициализации SDK есть возможность задать конфигурацию

ma('create', config);

Свойства объекта config

id

ID потока (Flow ID). Обязательный параметр.

Тип: string

batching

Объединение нескольких событий в один JSON-файл и отправка одним запросом.

Тип: boolean или

{
  time: number;
  count: number;
}

Возможные значения:

true — объединяет события. Отправка происходит:

каждые 2 секунды,
или если накопится 20 событий,
или когда произойдет событие pageview.

false — событие отправляется сразу без объединения.
{time: <TIME>, count: <COUNT>}

Значения по умолчанию: count (20), time (2000)

Приоритет отправки:

Произошло событие pageview.
Истекло время.
Накоплено 20 событий.

Заметка

События отправятся вне зависимости от выставленных условий при закрытии страницы или переходе на другую вкладку.

ecommerce

При включении (true) использует слой данных по имени dataLayer для получения событий электронной коммерции. Важно, чтобы события в dataLayer соответствовали формату GA4 или UA (Universal Analytics). Можно задать кастомное имя слоя данных.

Тип: boolean || string.

Значение по умолчанию: false

sendMethod

Метод отправки данных на сервер.

Тип:

Тип	Описание
`auto`	проверяет доступность метода `sendBeacon` и соответствие версий систем/браузеров. Если всё корректно, задаётся значение `beacon`, если некорректно — `xhr`
`beacon`	для отправки используется метод sendBeacon. Если невозможно вызвать, данные будут отправлены через `XMLHttpRequest`
`xhr`	для отправки через `XMLHttpRequest`
`double`	каждый запрос отправляется двумя методами: `sendBeacon` и `XMLHttpRequest`

Значение по умолчанию: xhr

outQueue

Настройка отправки событий (группы событий при batching) на сервер очередью. Помогает не терять события при проблемах с сетью или при закрытии / обновлении страницы.

Функции:

Что делает	Описание
Повторные попытки	Если отправка не удалась, SDK не отбрасывает события, а повторяет попытки через заданные интервалы
Сохранение при уходе со страницы	Неотправленные события из очереди сохраняются в браузере при закрытии вкладки, обновлении страницы, переходе на другую страницу
Восстановление при следующем заходе	При новом открытии страницы (того же сайта с тем же счётчиком) сохранённые события подхватываются и снова отправляются

Тип: boolean ||

	{
		reconnectTimeout: Array<number>;
		maxConnectionAttempts: number;
		maxStorageCount: number;
	}

Возможные значения:

false – очередь отключена. События отправляются сразу
true – очередь включена. Параметры отправки используются по умолчанию
{maxConnectionAttempts, reconnectTimeout, maxStorageCount}

Значения по умолчанию: maxConnectionAttempts (10), maxStorageCount (100), reconnectTimeout:

[2000, 5000, 10000, 30000, 60000, 5 * 60000];

Заметка

Неуказанные свойства принимаются как значения по умолчанию.

Параметры конфигурации:

Название	Описание
`reconnectTimeout`	Паузы (в миллисекундах) между повторными попытками отправки одного и того же события (группы событий) после ошибки
`maxConnectionAttempts`	Показывает, сколько раз подряд SDK будет пытаться отправить событие (группу событий), прежде чем считать его неудачным и перейти к следующему
`maxStorageCount`	Показывает, cколько последних неотправленных событий из очереди сохранять в `localStorage` браузера

sendPageView

Автоматическое определение переходов по страницам, отправка событий pageview.

Тип: boolean

Возможные значения:

false — автоматическая отправка Pageview не осуществляется
true — SDK автоматически отправляет pageview при инициализации и при каждой смене URL страницы

Значение по умолчанию: true

trackBounce

Включить точный показатель отказов. Время отправки события по умолчанию — 15 секунд, либо через указанное время (в секундах).

Тип: boolean | number

Значение по умолчанию: 15

plugins

Список плагинов, которые необходимо включить.

Тип

[{
  name: string;
  config?: any;
}, ...]

name — имя плагина
config — конфигурация плагина

Значение по умолчанию: [], нет включенных

Команды для настройки отправки событий

Вы можете вручную задать команды и параметры отправки событий в библиотеку МТС Аналитики. Подробнее — Команды для отправки событий в МТС Аналитику.

Плагины для расширения функционала SDK

Совет

Для расширения возможностей библиотеки можно дополнительно подключить плагины dataLayer, linker, error, performance. По умолчанию они отключены.

Чтобы подключить плагин, после инициализации SDK выполните команду

ma('addPlugin', '<PLUGIN_NAME>', <PLUGIN_OPTIONS>);

К методам плагина можно обращаться способом

ma('plugin', '<PLUGIN_NAME>', '<SOME_METHOD>', ...arguments);

Data Layer

Отслеживание и оправка всех событий, которые попали в уровень данных. SomeObject при вызове dataLayer.push(someObject) будет полностью отправлен в МТС Аналитику.

Инициализация

ma('addPlugin', 'dataLayer', '<DATA_LAYER_NAME>');

<DATA_LAYER_NAME> — имя слоя данных. Если не указано, по умолчанию ставится «dataLayer».

Linker

Включает механизм междоменного связывания сессий.

Тип:

{

  allowLinker: boolean;
  autoLink: string[];

}

Значение по умолчанию:

 {
   allowLinker: false,

   autoLink: []
}

Performance

Осуществляет сбор технических метрик производительности страниц пользователя. Сбор и отправка всех технических метрик происходит автоматически после включения плагина.

Инициализация

ma('addPlugin', 'performance');

Error

Плагин отправляет все необработанные ошибки (исключения JavaScript) автоматически. Внутри блока try-catch можно отправлять вручную с помощью метода trackError.

Инициализация

ma('addPlugin', 'error');

Ручная отправка ошибок

try {
  throw new Error()
} catch (e) {
  ma('plugin', 'error', 'trackError', {
    message: string, error?: Error, colno?: number, lineno?: number, filename?: string
  });
}

При инициализации обязательно заполните поле message. Если message не был передан, подставляется значение «JS Exception. Добавьте описание ошибки».

Шаг 2. Перенести код SDK на сайт

Скопируйте код SDK и добавьте его в HTML каждой страницы сайта. Расположите фрагмент в разделе <head> (как можно выше) или <body>.

Пример настроенного скрипта

включён dataLayer
выключёна отправка pageview

<script>
  (function (sdk) {
    window[sdk] = window[sdk] || function () {
      (window[sdk].a = window[sdk].a || []).push(arguments);
    };
    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://static.a.mts.ru/web-sdk/analytics.js?name=' + sdk;
    document.head.appendChild(script);
  })('ma');

  ma('create', {
    id: '11111111-1111-1111-1111-111111111111',
    sendPageView: false,
    plugins: [{ name: 'dataLayer' }],
  });
</script>

Шаг 1. Настроить код SDK​

Инициализация и конфигурация библиотеки​

Свойства объекта config​

id​

batching​

ecommerce​

sendMethod​

outQueue​

sendPageView​

trackBounce​

plugins​

Команды для настройки отправки событий​

Плагины для расширения функционала SDK​

Data Layer​

Linker​

Performance​

Error​

Шаг 2. Перенести код SDK на сайт​

Пример настроенного скрипта​

Шаг 1. Настроить код SDK

Инициализация и конфигурация библиотеки

Свойства объекта config

id

batching

ecommerce

sendMethod

outQueue

sendPageView

trackBounce

plugins

Команды для настройки отправки событий

Плагины для расширения функционала SDK

Data Layer

Linker

Performance

Error

Шаг 2. Перенести код SDK на сайт

Пример настроенного скрипта