IKuznetsov: Новая страница: «= Пользовательские события = Ключ-АСТРОМ поддерживает пользовательские события для отслеживания взаимодействий пользователей, бизнес-показателей и сигналов, специфичных для приложения. События также можно обогащать перед отправкой, применяя модифи...»

2026-08-19T16:51:27Z

Новая страница: «= Пользовательские события = Ключ-АСТРОМ поддерживает пользовательские события для отслеживания взаимодействий пользователей, бизнес-показателей и сигналов, специфичных для приложения. События также можно обогащать перед отправкой, применяя модифи...»

Новая страница

= Пользовательские события =

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

== Свойства событий и сессий ==

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

Для определения нового свойства:

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

Ключ-АСТРОМ автоматически добавляет префикс к имени поля: <code>event_properties.</code> или <code>session_properties.</code> в зависимости от выбранного типа свойства. Например, имя поля <code>cart.total_value</code> станет <code>event_properties.cart.total_value</code>.

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

Пользовательские события отправляются с помощью <code>Astromkey.sendEvent(...)</code> с использованием необязательных свойств продолжительности и самого события.

Рассмотрите базовое использование.

'''Kotlin'''
<pre>
// Простое событие
Astromkey.sendEvent(EventData())

// Событие с указанием длительности (в миллисекундах)
Astromkey.sendEvent(EventData().withDuration(150))
</pre>

'''Java'''
<pre>
// Простое событие
Astromkey.sendEvent(new EventData());

// Событие с указанием длительности (в миллисекундах)
Astromkey.sendEvent(new EventData().withDuration(150));
</pre>

== Добавить свойства события ==

Пользовательские свойства обеспечивают контекст для сообщаемых событий. Ключи свойств должны иметь префикс <code>event_properties.</code>.

'''Kotlin'''
<pre>
Astromkey.sendEvent(
EventData()
.withDuration(250)
.addEventProperty("event_properties.checkout_step", "payment_confirmed")
.addEventProperty("event_properties.cart_value", 149.99)
.addEventProperty("event_properties.item_count", 3)
)
</pre>

'''Java'''
<pre>
Astromkey.sendEvent(new EventData()
.withDuration(250)
.addEventProperty("event_properties.checkout_step", "payment_confirmed")
.addEventProperty("event_properties.cart_value", 149.99)
.addEventProperty("event_properties.item_count", 3)
);
</pre>

== Правила наименования свойств ==

Правила и ограничения именования см. в разделе «Свойства событий и сессий».

== Модификаторы событий ==

Модификаторы событий перехватывают события до их отправки. Их можно использовать для добавления общих свойств, удаления конфиденциальной информации или фильтрации событий.

На '''Android''' модификаторы работают с представлением события в виде <code>JSONObject</code>.

=== Добавить модификатор события ===

'''Kotlin'''
<pre>
val modifier = EventModifier { event ->
// Добавить контекст варианта сборки ко всем событиям
event.put("event_properties.build_type", BuildConfig.BUILD_TYPE)
event.put("event_properties.flavor", BuildConfig.FLAVOR)
event
}

Astromkey.addEventModifier(modifier)
</pre>

'''Java'''
<pre>
EventModifier modifier = (JSONObject event) -> {
// Добавить контекст варианта сборки ко всем событиям
event.put("event_properties.build_type", BuildConfig.BUILD_TYPE);
event.put("event_properties.flavor", BuildConfig.FLAVOR);
return event;
};

Astromkey.addEventModifier(modifier);
</pre>

=== Фильтрация событий ===

Возврат <code>null</code> отменяет событие.

'''Kotlin'''
<pre>
val modifier = EventModifier { event ->
// События, происходящие в активности com.example.MainActivity, будут отброшены.
if (event.optString("view.detected_name") == "com.example.MainActivity") {
return@EventModifier null
}
event
}

Astromkey.addEventModifier(modifier)
</pre>

'''Java'''
<pre>
EventModifier modifier = (JSONObject event) -> {
// События, происходящие в активности com.example.MainActivity, будут отброшены.
if ("com.example.MainActivity".equals(event.optString("view.detected_name"))) {
return null;
}
return event;
};

Astromkey.addEventModifier(modifier);
</pre>

=== Удалите конфиденциальные данные ===

'''Kotlin'''
<pre>
val modifier = EventModifier { event ->
// Удаление идентификаторов пользователей из URL-адресов
val url = event.optString("url.full", null)
if (url != null) {
val redactedUrl = url.replace(Regex("/users/\\w+/"), "/users/{id}/")
event.put("url.full", redactedUrl)
}
event
}

Astromkey.addEventModifier(modifier)
</pre>

'''Java'''
<pre>
EventModifier modifier = (JSONObject event) -> {
// Удаление идентификаторов пользователей из URL-адресов
String url = event.optString("url.full", null);
if (url != null) {
String redactedUrl = Pattern.compile("/users/\\w+/")
.matcher(url)
.replaceAll("/users/{id}/");
event.put("url.full", redactedUrl);
}
return event;
};

Astromkey.addEventModifier(modifier);
</pre>

=== Удалить модификаторы событий ===

'''Kotlin'''
<pre>
// Сохраните модификатор при его добавлении
val modifier = EventModifier { event ->
event.put("event_properties.custom", "value")
event
}

Astromkey.addEventModifier(modifier)

// Удалять, когда больше не требуется
Astromkey.removeEventModifier(modifier)
</pre>

'''Java'''
<pre>
// Сохраните модификатор при его добавлении
EventModifier modifier = (JSONObject event) -> {
event.put("event_properties.custom", "value");
return event;
};

Astromkey.addEventModifier(modifier);

// Удалять, когда больше не требуется
Astromkey.removeEventModifier(modifier);
</pre>

=== Ограничения модификаторов ===

Модификаторы событий имеют ограничения на то, какие поля могут быть изменены для обеспечения целостности данных.

'''Изменяемые поля'''

Следующие поля можно изменять или добавлять:

* <code>event_properties.*</code> — свойства события.
* <code>session_properties.*</code> — свойства сессии (только для событий, связанных со свойствами сессии).
* <code>url.full</code> — полный URL-адрес запроса.
* <code>exception.stack_trace</code> — трассировка стека исключений.

Все остальные поля доступны только для чтения и не могут быть изменены. Исходные значения сохраняются.

=== Важные соображения ===

* '''Потокобезопасность''' — модификаторы могут вызываться из любого потока; убедитесь, что ваш код потокобезопасен.
* '''Производительность''' — поддерживайте эффективность модификаторов; они применяются к каждому событию.

=== Пример модификатора: условное обогащение событий ===

Следующий пример демонстрирует, как обогащать информацию только для определенных типов событий. Он добавляет контекст к HTTP-событиям (для сегментации API) и к событиям ошибок (для более быстрой обработки).

'''Kotlin'''
<pre>
fun setupConditionalEnrichment(apiClientName: String) {
val modifier = EventModifier { event ->
// Добавлять контекст только для HTTP-событий
if (event.optBoolean("characteristics.has_request")) {
event.put("event_properties.api_client", apiClientName)
event.put("event_properties.api_kind", "backend")
}

// Добавлять контекст только для событий ошибок
if (event.optBoolean("characteristics.has_error")) {
event.put("event_properties.triage_owner", "mobile")
event.put("event_properties.triage_severity", "error")
}

event
}

Astromkey.addEventModifier(modifier)
}
</pre>

'''Java'''
<pre>
public void setupConditionalEnrichment(final String apiClientName) {
EventModifier modifier = (JSONObject event) -> {
// Добавлять контекст только для HTTP-событий
if (event.optBoolean("characteristics.has_request")) {
event.put("event_properties.api_client", apiClientName);
event.put("event_properties.api_kind", "backend");
}

// Добавлять контекст только для событий ошибок
if (event.optBoolean("characteristics.has_error")) {
event.put("event_properties.triage_owner", "mobile");
event.put("event_properties.triage_severity", "error");
}

return event;
};

Astromkey.addEventModifier(modifier);
}
</pre>

== Связанные темы ==

* Производительность веб-запросов — модификаторы HTTP-событий.
* Сообщения об ошибках и сбоях — события исключений.
* Конфигурация — конфигурация агента.

Пользовательские события - История изменений