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

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

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

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

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

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

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

# Перейдите в раздел '''Ключевые показатели опыта''' > '''Обзор'''.
# Выберите '''Веб''', чтобы просмотреть все веб-интерфейсы.
# Выберите интерфейс, который хотите настроить.
# На вкладке '''Настройки''' выберите '''Свойства захвата'''.
# В разделе '''Свойства захваченного события''' выберите '''Создать новое свойство'''.
# В поле '''Определить ключ свойства события''' введите ключ свойства (например, <code>cart.total_value</code>). Ключ автоматически получает префикс <code>event_properties.</code>, поэтому результирующее поле будет <code>event_properties.cart.total_value</code>.
# В разделе '''Определить источник''' выберите '''Добавить этап обработки''' и укажите, откуда следует извлекать значение. Для вложенных данных можно добавить несколько этапов обработки — результат каждого этапа передается в качестве входных данных для следующего.
# Выберите '''Добавить''', чтобы сохранить правило.

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

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

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

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

Если на этапе обработки считывается <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>, чтобы предотвратить перехват учетных данных.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Перейдите в '''Настройки''' > '''Обработка и контекстуализация''' > '''OpenPipeline''' > '''Пользовательские события''' > '''Конвейеры'''.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Перейдите в раздел '''Обработка''' > '''Добавить''' (или, если обработчики уже определены) > '''DQL''' и определите обработчик:
#* Описательное название — например, <code>Derive session property from cart value</code>
#* Условие соответствия — фильтр для событий, обладающих свойством события, например: <code>isNotNull(event_properties.cart.total_value)</code>
#* Определение DQL-процессора — два оператора <code>fieldsAdd</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''' > '''Пользовательские события''' > '''Конвейеры'''.
# Выберите существующий конвейер или создайте новый. Чтобы создать новый конвейер, выберите '''Конвейер''' и введите имя.
# Перейдите в раздел '''Обработка''' > '''Добавить''' (или, если обработчики уже определены) > '''DQL''' и определите обработчик:
#* Описательное название — например, <code>Set user identifier from username</code>
#* Условие соответствия — фильтр для событий, обладающих свойством события, например: <code>isNotNull(event_properties.username)</code>
#* Определение процессора DQL:
<pre>
fieldsAdd user.identifier = event_properties.username
</pre>

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

== Пределы ==

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

* Имя поля может иметь максимальную длину 100 символов, включая префикс <code>event_properties.</code> или <code>session_properties.</code>.
* Имя поля может содержать только буквы (<code>A–Z</code>, <code>a–z</code>), цифры (<code>0–9</code>), подчеркивания (<code>_</code>) и точки (<code>.</code>).
* Для каждого интерфейса можно настроить до 100 свойств захватываемых событий.
* На одном интерфейсе можно разрешить передачу до 200 свойств через API.
* В рамках одного события можно отправить до 50 свойств.
* В каждую сессию можно добавить до 500 свойств сессии.
* Строковые значения могут иметь максимальную длину в 1000 символов.