Захват свойств событий и сессий для веб-интерфейсов

Материал из Документация Ключ-АСТРОМ
Версия от 15:14, 19 августа 2026; IKuznetsov (обсуждение | вклад) (Новая страница: «= Захват свойств событий и сессий для веб-интерфейсов = Используйте свойства событий и сессий, чтобы обогатить данные '''RUM''' контекстом бизнеса или приложения и настроить мониторинг в соответствии с вашими целями. Вы можете собирать их следующими спосо...»)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

Захват свойств событий и сессий для веб-интерфейсов

Используйте свойства событий и сессий, чтобы обогатить данные RUM контекстом бизнеса или приложения и настроить мониторинг в соответствии с вашими целями. Вы можете собирать их следующими способами:

  • Получайте информацию о свойствах событий через пользовательский интерфейс Ключ-АСТРОМ — извлекайте свойства событий из элементов DOM, файлов cookie или переменных JavaScript.
  • Отправляйте данные о свойствах через JavaScript API — любые доступные на стороне клиента данные в качестве свойств события или сессии.
  • Обогащайте свойства в OpenPipeline — агрегируйте свойства сессии из свойств события или устанавливайте идентификатор пользователя во время приема данных.

Захват свойств событий через пользовательский интерфейс Ключ-АСТРОМ

Вы можете собирать свойства событий непосредственно с веб-страницы, определяя правила захвата. Каждое правило извлекает значение через один или несколько упорядоченных этапов обработки и прикрепляет его к событиям пользователя в качестве свойства события.

Для получения свойства события:

  1. Перейдите в раздел Ключевые показатели опыта > Обзор.
  2. Выберите Веб, чтобы просмотреть все веб-интерфейсы.
  3. Выберите интерфейс, который хотите настроить.
  4. На вкладке Настройки выберите Свойства захвата.
  5. В разделе Свойства захваченного события выберите Создать новое свойство.
  6. В поле Определить ключ свойства события введите ключ свойства (например, cart.total_value). Ключ автоматически получает префикс event_properties., поэтому результирующее поле будет event_properties.cart.total_value.
  7. В разделе Определить источник выберите Добавить этап обработки и укажите, откуда следует извлекать значение. Для вложенных данных можно добавить несколько этапов обработки — результат каждого этапа передается в качестве входных данных для следующего.
  8. Выберите Добавить, чтобы сохранить правило.

Для получения информации о свойствах, настроенных в пользовательском интерфейсе, требуется JavaScript RUM версии 1.341+.

Этапы обработки

Доступны следующие этапы обработки. Этапы выполняются последовательно, каждый из них передает свой результат следующему: этапы захвата значения считывают данные со страницы, а этапы преобразования значения обрабатывают результат предыдущего этапа. Первый этап в последовательности начинается без какого-либо входного сигнала.

Этап обработки Группа Описание Пример
CSS-селектор Захват значения Запускается document.querySelector() с заданным селектором. Селектор #username возвращает элемент, соответствующий заданному значению document.querySelector("#username").
Атрибут DOM Захват значения Считывает указанный атрибут из HTML-элемента, переданного на предыдущем шаге. Должен следовать за шагом выбора CSS-селектора. Функция Attribute title возвращает значение атрибута элемента title.
Cookie Захват значения Считывает значение указанного файла cookie. Функция Cookie user_name возвращает значение файла user_name cookie.
Доступ к свойству Захват значения Считывает именованное свойство из выходных данных предыдущего шага или из window, если он использовался в качестве первого шага. Свойство innerText возвращает текстовое содержимое элемента, переданного на предыдущем шаге.
Разобрать значение в формате JSON Преобразовать значение Анализирует входную строку как JSON и возвращает результирующий объект. Ввод '{"tier":"gold"}' возвращает объект {tier: "gold"}.

Например, чтобы получить имя пользователя, отображаемое в элементе с ID username, добавьте CSS-селектор с селектором #username, а затем Доступ к свойству со свойством innerText. Чтобы получить значение из объекта JSON, хранящегося в localStorage, используйте цепочку свойств доступа (localStorage), (ключ хранилища), (Разобрать значение как JSON) и (свойство для чтения).

Если на этапе обработки считывается value атрибут или свойство элемента ввода пароля — элемента, type атрибут которого равен password или который autocomplete содержит current-password или new-password — захваченное значение автоматически маскируется и отображается как <password>, чтобы предотвратить перехват учетных данных.

Сообщайте о свойствах через JavaScript API

Вы также можете передавать информацию о свойствах событий и сессий из собственного кода, используя JavaScript API. Чтобы предотвратить потерю ненастроенных свойств во время обработки данных, необходимо добавить каждое свойство в список разрешенных.

Разрешить свойства, передаваемые через API

Чтобы разрешить использование заявленного свойства:

  1. Перейдите в раздел Ключевые показатели опыта > Обзор.
  2. Выберите Веб, чтобы просмотреть все веб-интерфейсы.
  3. Выберите интерфейс, который хотите настроить.
  4. На вкладке Настройки выберите Свойства захвата.
  5. В разделе Разрешенные свойства, передаваемые через API выберите Новое свойство.
  6. Введите ключ свойства.
  7. Если вы хотите, чтобы проверка ключа свойства игнорировала регистр, включите параметр Проверка ключа свойства должна быть нечувствительной к регистру.

Отправка свойств события и сессии

После того, как свойство будет разрешено, вы можете начать отправлять его через JavaScript API.

Отправить свойства события

При отправке сообщений о событиях через JavaScript API с помощью sendEvent или sendException, вы можете добавлять свойства событий в качестве параметров. Чтобы добавить свойства событий к любому событию, включая те, которые отправляются самим JavaScript RUM, используйте addEventModifier.

При отправке или добавлении свойства события всегда указывайте префикс event_properties..

Отправить свойства сессии

Свойства сессии всегда отправляются как отдельные события. Для отправки свойства сессии используйте sendSessionPropertyEvent. Для включения дополнительных свойств сессии в это событие используйте addEventModifier.

При отправке или добавлении свойства сессии всегда указывайте префикс session_properties..

Агрегировать свойства сессии на основе свойств события

Свойства сессии можно получить из свойств события и агрегировать в рамках сессии с помощью OpenPipeline. Для каждого свойства сессии вы выбираете способ агрегирования значений, сообщаемых в течение сессии:

  • Для любого типа свойства можно указать либо Первое значение, либо Последнее значение. По умолчанию используется Последнее значение.
  • Для числовых свойств можно дополнительно использовать Min, Max, Avg или Sum.

Для объединения свойств сессии и свойств событий:

  1. Перейдите в Настройки > Обработка и контекстуализация > OpenPipeline > Пользовательские события > Конвейеры.
  2. Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите Конвейер и введите имя.
  3. Перейдите в раздел Обработка > Добавить (или, если обработчики уже определены) > DQL и определите обработчик:
    • Описательное название — например, Derive session property from cart value
    • Условие соответствия — фильтр для событий, обладающих свойством события, например: isNotNull(event_properties.cart.total_value)
    • Определение DQL-процессора — два оператора fieldsAdd: первый записывает значение свойства события в пространство имен свойств сессии, а второй объявляет метод агрегации, например:
fieldsAdd session_properties.cart.total_value = event_properties.cart.total_value,
  session_properties_aggregation.cart.total_value = "Max"

Значение агрегации представляет собой строку. Допустимые значения: "First", "Last", "Min", "Max", "Avg" и "Sum". "Min", "Max", "Avg" и "Sum" применяются только к числовым свойствам. Вы можете опустить строку агрегации fieldsAdd, чтобы использовать значение по умолчанию ("Last").

Дополните идентификатор пользователя свойствами события

С помощью OpenPipeline вы можете получить идентификатор пользователя для сессии из свойства захваченного или зарегистрированного события. Это позволяет установить идентификатор пользователя из данных приложения, в качестве альтернативы вызову метода identifyUser.

Чтобы заполнить идентификатор пользователя из свойства события:

  1. Перейдите в Настройки > Обработка и контекстуализация > OpenPipeline > Пользовательские события > Конвейеры.
  2. Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите Конвейер и введите имя.
  3. Перейдите в раздел Обработка > Добавить (или, если обработчики уже определены) > DQL и определите обработчик:
    • Описательное название — например, Set user identifier from username
    • Условие соответствия — фильтр для событий, обладающих свойством события, например: isNotNull(event_properties.username)
    • Определение процессора DQL:
fieldsAdd user.identifier = event_properties.username

Возможно, вы увидите предупреждение, поскольку user.identifier поле входит в предопределенный набор полей builtin-sensitive-user-events-and-sessions. Тем не менее, вы можете использовать его для обогащения данных. Подробную информацию о контроле доступа к конфиденциальным полям см. в разделе «Разрешения для полей».

Пределы

К свойствам событий и сессий применяются следующие ограничения:

  • Имя поля может иметь максимальную длину 100 символов, включая префикс event_properties. или session_properties..
  • Имя поля может содержать только буквы (A–Z, a–z), цифры (0–9), подчеркивания (_) и точки (.).
  • Для каждого интерфейса можно настроить до 100 свойств захватываемых событий.
  • На одном интерфейсе можно разрешить передачу до 200 свойств через API.
  • В рамках одного события можно отправить до 50 свойств.
  • В каждую сессию можно добавить до 500 свойств сессии.
  • Строковые значения могут иметь максимальную длину в 1000 символов.
Источник — https://doc.ruscomtech.ru/index.php?title=Захват_свойств_событий_и_сессий_для_веб-интерфейсов&oldid=6567