Захват свойств событий и сессий для веб-интерфейсов: различия между версиями

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


* Получайте информацию о свойствах событий через пользовательский интерфейс Ключ-АСТРОМ — извлекайте свойства событий из элементов '''DOM''', файлов cookie или переменных '''JavaScript'''.
* Получайте информацию о свойствах событий через пользовательский интерфейс Ключ-АСТРОМ — извлекайте свойства событий из элементов '''DOM''', файлов cookie или переменных '''JavaScript'''.
Строка 8: Строка 7:


== Захват свойств событий через пользовательский интерфейс Ключ-АСТРОМ ==
== Захват свойств событий через пользовательский интерфейс Ключ-АСТРОМ ==
Вы можете собирать свойства событий непосредственно с веб-страницы, определяя правила захвата. Каждое правило извлекает значение через один или несколько упорядоченных этапов обработки и прикрепляет его к событиям пользователя в качестве свойства события.
Вы можете собирать свойства событий непосредственно с веб-страницы, определяя правила захвата. Каждое правило извлекает значение через один или несколько упорядоченных этапов обработки и прикрепляет его к событиям пользователя в качестве свойства события.


Строка 25: Строка 23:


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


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


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


=== Разрешить свойства, передаваемые через API ===
=== Разрешить свойства, передаваемые через API ===
Чтобы разрешить использование заявленного свойства:
Чтобы разрешить использование заявленного свойства:


Строка 64: Строка 74:


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


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


Строка 74: Строка 82:


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


Строка 80: Строка 87:


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


Строка 90: Строка 96:
# Перейдите в '''Настройки''' > '''Обработка и контекстуализация''' > '''OpenPipeline''' > '''Пользовательские события''' > '''Конвейеры'''.
# Перейдите в '''Настройки''' > '''Обработка и контекстуализация''' > '''OpenPipeline''' > '''Пользовательские события''' > '''Конвейеры'''.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Перейдите в раздел '''Обработка''' > '''Добавить''' (или, если обработчики уже определены) > '''DQL''' и определите обработчик:
# Перейдите в раздел '''Обработка''' и настройте обработчик:
#* Описательное название — например, <code>Derive session property from cart value</code>
#* Задайте описательное название — например, <code>Derive session property from cart value</code>.
#* Условие соответствия — фильтр для событий, обладающих свойством события, например: <code>isNotNull(event_properties.cart.total_value)</code>
#* Настройте условие соответствия для событий, обладающих свойством события, например: <code>isNotNull(event_properties.cart.total_value)</code>.
#* Определение DQL-процессора — два оператора <code>fieldsAdd</code>: первый записывает значение свойства события в пространство имен свойств сессии, а второй объявляет метод агрегации, например:
#* Укажите правило для записи значения свойства события в пространство имен свойств сессии и объявления метода агрегации. Допустимые методы агрегации: <code>"First"</code>, <code>"Last"</code>, <code>"Min"</code>, <code>"Max"</code>, <code>"Avg"</code> и <code>"Sum"</code>. Методы <code>"Min"</code>, <code>"Max"</code>, <code>"Avg"</code> и <code>"Sum"</code> применяются только к числовым свойствам.
<pre>
fieldsAdd session_properties.cart.total_value = event_properties.cart.total_value,
  session_properties_aggregation.cart.total_value = "Max"
</pre>
 
Значение агрегации представляет собой строку. Допустимые значения: <code>"First"</code>, <code>"Last"</code>, <code>"Min"</code>, <code>"Max"</code>, <code>"Avg"</code> и <code>"Sum"</code>. <code>"Min"</code>, <code>"Max"</code>, <code>"Avg"</code> и <code>"Sum"</code> применяются только к числовым свойствам. Вы можете опустить строку агрегации <code>fieldsAdd</code>, чтобы использовать значение по умолчанию (<code>"Last"</code>).


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


Строка 109: Строка 108:
# Перейдите в '''Настройки''' > '''Обработка и контекстуализация''' > '''OpenPipeline''' > '''Пользовательские события''' > '''Конвейеры'''.
# Перейдите в '''Настройки''' > '''Обработка и контекстуализация''' > '''OpenPipeline''' > '''Пользовательские события''' > '''Конвейеры'''.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Перейдите в раздел '''Обработка''' > '''Добавить''' (или, если обработчики уже определены) > '''DQL''' и определите обработчик:
# Перейдите в раздел '''Обработка''' и настройте обработчик:
#* Описательное название — например, <code>Set user identifier from username</code>
#* Задайте описательное название — например, <code>Set user identifier from username</code>.
#* Условие соответствия — фильтр для событий, обладающих свойством события, например: <code>isNotNull(event_properties.username)</code>
#* Настройте условие соответствия для событий, обладающих свойством события, например: <code>isNotNull(event_properties.username)</code>.
#* Определение процессора DQL:
#* Настройте правило для присвоения значения свойства события полю <code>user.identifier</code>.
<pre>
fieldsAdd user.identifier = event_properties.username
</pre>


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


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



Текущая версия от 22:00, 16 ноября 2026

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

Используйте свойства событий и сессий, чтобы обогатить данные Мониторинга реального пользователя (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. Перейдите в раздел Обработка и настройте обработчик:
    • Задайте описательное название — например, Derive session property from cart value.
    • Настройте условие соответствия для событий, обладающих свойством события, например: isNotNull(event_properties.cart.total_value).
    • Укажите правило для записи значения свойства события в пространство имен свойств сессии и объявления метода агрегации. Допустимые методы агрегации: "First", "Last", "Min", "Max", "Avg" и "Sum". Методы "Min", "Max", "Avg" и "Sum" применяются только к числовым свойствам.

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

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

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

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

Возможно, вы увидите предупреждение, поскольку поле 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 символов.