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

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

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

Настройка кода SDK

В статье приведена пошаговая инструкция по добавлению базового кода библиотеки на сайт. Необходимо вставить скрипт в раздел <head> или <body> каждой страницы. Ключевым элементом является указание идентификатора потока (FLOW_ID), который необходим для отправки данных; если ID отсутствует, его можно запросить через поддержку. Имя переменной SDK (по умолчанию ma) можно изменить по желанию.

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

При создании экземпляра SDK с помощью команды ma('create', config) можно задать различные параметры для оптимизации сбора данных.

id Обязательный параметр типа string, содержащий идентификатор потока.

batching Параметр типа boolean или объект с настройками времени и количества событий, позволяющий объединять несколько событий в один запрос.

true: события объединяются и отправляются каждые 2 секунды, при накоплении 20 событий или при событии pageview.
false: события отправляются мгновенно.
При закрытии страницы или переходе на другую вкладку события отправляются независимо от настроек батчинга.

ecommerce Параметр типа boolean или string. При включении использует слой данных (dataLayer) для получения событий электронной коммерции в формате GA4 или UA. По умолчанию отключен.

sendMethod Метод отправки данных на сервер (auto, beacon, xhr, double). По умолчанию используется xhr. Метод auto автоматически выбирает между beacon и xhr в зависимости от поддержки браузером.

outQueue Настройка отправки событий очередью для предотвращения потери данных при проблемах с сетью или закрытии страницы.

false: очередь отключена.
true: очередь включена с параметрами по умолчанию.
Объект с настройками: reconnectTimeout (интервалы повторных попыток), maxConnectionAttempts (максимум попыток отправки), maxStorageCount (максимум сохраняемых в localStorage событий).

sendPageView Параметр типа boolean. При true SDK автоматически отправляет событие pageview при инициализации и смене URL. По умолчанию включен.

trackBounce Включает точный показатель отказов. Тип boolean или number (время в секундах). По умолчанию 15 секунд.

sessionTimeout Время бездействия пользователя (в секундах) до завершения сессии. Допустимый диапазон: от 1800 до 28800 секунд. По умолчанию 1800 секунд.

plugins Список подключаемых плагинов. По умолчанию пуст.

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

В тексте вы найдете руководство по решению задачи ручной настройки команд и параметров отправки событий в библиотеку МТС Аналитики.

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

Для расширения возможностей библиотеки можно подключить плагины dataLayer, linker, error, performance. Подключение осуществляется командой ma('addPlugin', '<PLUGIN_NAME>', <PLUGIN_OPTIONS>).

Data Layer Отслеживает и отправляет события из указанного слоя данных. Инициализируется указанием имени слоя (по умолчанию dataLayer).

Linker Включает междоменное связывание сессий. Настройки включают allowLinker (boolean) и autoLink (массив доменов). По умолчанию отключено.

Performance Автоматически собирает и отправляет технические метрики производительности страниц.

Error Автоматически отправляет необработанные ошибки JavaScript. Также поддерживает ручную отправку ошибок через метод trackError внутри блоков try-catch, где обязательно поле message.

Перенос кода SDK на сайт

В статье приведена пошаговая инструкция по интеграции настроенного кода на веб-ресурс. Код необходимо разместить в начале HTML-документа. Приведен пример скрипта, демонстрирующего инициализацию с отключенной автоматической отправкой pageview и подключенным плагином dataLayer.

Для передачи данных о поведении пользователя в МТС Аналитику необходимо настроить поток данных через библиотеку 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

sessionTimeout

Задаёт время бездействия пользователя на сайте, после которого текущая сессия будет завершена (в секундах). Изменения затронут только новые сессии.

Тип: number (целое)

Значение по умолчанию: 1 800 (30 минут)

Ограничение	Допустимое значение
Минимальное	1 800 (30 минут)
Максимальное	28 800 (8 часов)

Если значение выходит за пределы допустимого диапазона, SDK покажет предупреждение в консоли браузера и продолжит работу со значением по умолчанию — 1 800 (30 минут).

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​

sessionTimeout​

plugins​

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

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

Data Layer​

Linker​

Performance​

Error​

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

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

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

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

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

id

batching

ecommerce

sendMethod

outQueue

sendPageView

trackBounce

sessionTimeout

plugins

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

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

Data Layer

Linker

Performance

Error

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

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