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

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

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

Настроить код SDK

В статье приведена пошаговая инструкция по добавлению базового кода библиотеки на сайт. Для корректной работы необходимо указать идентификатор потока (Flow ID), который можно запросить у поддержки, если он отсутствует. Имя переменной для SDK (по умолчанию ma) можно изменить на любое другое.

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

В тексте вы найдете руководство по решению задачи настройки параметров отправки данных при инициализации SDK через команду ma('create', config).

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

id: Обязательный параметр типа string, содержащий ID потока для идентификации источника данных.
batching: Параметр типа boolean или объект с настройками времени и количества событий. Позволяет объединять события в один запрос для оптимизации. Отправка происходит при наступлении определенных условий (истечение времени, накопление событий или смена страницы) или при закрытии страницы.
ecommerce: Включение сбора данных электронной коммерции из слоя данных (dataLayer). Поддерживает форматы GA4 или UA. Тип: boolean или string.
sendMethod: Выбор метода отправки данных на сервер (auto, beacon, xhr, double). По умолчанию используется xhr.
outQueue: Настройка очереди событий для предотвращения потери данных при проблемах с сетью или закрытии страницы. Включает повторные попытки отправки и сохранение данных в localStorage.
sendPageView: Автоматическая отправка событий pageview при инициализации или смене URL. По умолчанию включено (true).
trackBounce: Настройка точного показателя отказов. По умолчанию событие отправляется через 15 секунд бездействия.
sessionTimeout: Время бездействия пользователя в секундах, после которого сессия завершается. Допустимый диапазон от 30 минут до 8 часов.
plugins: Список подключаемых плагинов для расширения функционала.

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

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

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

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

Data Layer: Автоматическая отправка всех событий из указанного слоя данных.
Linker: Включает междоменное связывание сессий для отслеживания пользователей на нескольких доменах.
Performance: Автоматический сбор технических метрик производительности страниц.
Error: Автоматический сбор необработанных ошибок JavaScript. Также поддерживает ручную отправку ошибок через метод trackError.

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

В тексте вы найдете руководство по решению задачи размещения кода SDK на страницах сайта. Скрипт необходимо добавить в раздел <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

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 на сайт

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