IKuznetsov: Новая страница: «= Инструментарий для анализа действий пользователя = Действие пользователя представляет собой важную операцию в вашем приложении — оно объединяет запросы, навигации и ошибки, возникающие в результате одного взаимодействия пользователя, в одно событ...»

2026-08-19T16:56:22Z

Новая страница: «= Инструментарий для анализа действий пользователя = Действие пользователя представляет собой важную операцию в вашем приложении — оно объединяет запросы, навигации и ошибки, возникающие в результате одного взаимодействия пользователя, в одно событ...»

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

= Инструментарий для анализа действий пользователя =

Действие пользователя представляет собой важную операцию в вашем приложении — оно объединяет запросы, навигации и ошибки, возникающие в результате одного взаимодействия пользователя, в одно событие. Полный концептуальный обзор того, как начинаются, заканчиваются действия пользователя и какие данные они собирают, см. в разделе «Действия пользователя». Разделы ниже содержат только сведения об инструментировании, специфичные для '''Android'''.

== Автоматизированные измерительные приборы ==

Автоматические действия пользователя вызываются взаимодействием пользователя с обработчиком действий.

=== Названия действий пользователя ===

Общий шаблон именования описан в разделе «Действия пользователя». На '''Android''' две части имени обрабатываются следующим образом:

* '''Имя экрана''': Полное имя класса, в котором <code>Activity</code> произошло касание, например, <code>com.example.MainActivity</code>. Если вы зададите пользовательское имя представления через API, будет использоваться это имя.
* '''Имя элемента''': ЕдиныйАгент использует имя типа компонента элемента, который обрабатывал выбор, например, <code>Button</code> или <code>MaterialCardView</code>.

'''Нажмите на кнопку в <code>com.example.MainActivity</code>'''

=== Примеры обработчиков действий ===

Обработчик действий — это код приложения, привязанный к взаимодействию пользователя, который реализует поведение, запускаемое этим взаимодействием. Только взаимодействия пользователя, к которым прикреплен обработчик действий, могут приводить к выполнению действия пользователем.

* '''Представление Android''': Логика выполняется в <code>OnClickListener</code>.
* '''Jetpack Compose''': Логика выполняется с помощью модификатора <code>clickable</code>.

Подробное описание обработчиков действий см. в разделе «Взаимодействие с пользователем».

=== Настройка автоматической инструментальной обработки ===

Используется <code>Astromkey.setAutomaticUserActionDetection(boolean)</code> для активации или деактивации автоматического определения действий пользователя во время выполнения. Автоматическое определение активно по умолчанию.

При отключении автоматического определения действия пользователя, их взаимодействие с пользователем больше не запускает автоматическое создание действий. Действия пользователя, созданные вручную, <code>createUserAction</code> остаются без изменений.

'''Kotlin'''
<pre>
Astromkey.setAutomaticUserActionDetection(false)
</pre>

'''Java'''
<pre>
Astromkey.setAutomaticUserActionDetection(false);
</pre>

== Ручные измерительные приборы ==

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

=== Создать действие пользователя ===

Используйте <code>Astromkey.createUserAction(UserActionConfiguration)</code> для запуска действия пользователя, инициируемого API. Передайте объект <code>UserActionConfiguration</code> с пользовательским именем, описывающим отслеживаемый вами рабочий процесс. Вызовите функцию <code>complete()</code> по завершении рабочего процесса.

<code>createUserAction</code> всегда возвращает действие пользователя, а некорректное использование (например, указание пустого пользовательского имени) обрабатывается без уведомления.

'''Kotlin'''
<pre>
val userAction = Astromkey.createUserAction(
UserActionConfiguration("Процесс оформления заказа")
)

// ... выполнить рабочий процесс ...

userAction.complete()
</pre>

'''Java'''
<pre>
UserAction userAction = Astromkey.createUserAction(
new UserActionConfiguration("Процесс оформления заказа")
);

// ... выполнить рабочий процесс ...

userAction.complete();
</pre>

=== Автоматическое завершение ===

По умолчанию вызов необходимо выполнить <code>complete()</code> явно. Если ваш рабочий процесс запускает веб-запросы, и вы хотите, чтобы действие пользователя автоматически завершалось после завершения всех выполняющихся запросов, активируйте этот параметр <code>withCompleteAutomatically(true)</code>.

'''Kotlin'''
<pre>
val userAction = Astromkey.createUserAction(
UserActionConfiguration("Процесс оформления заказа")
.withCompleteAutomatically(true)
)

// Действие пользователя завершается автоматически после окончания обработки ожидающих запросов.
// Вы по-прежнему можете вызвать метод complete(), чтобы закрыть его раньше.
</pre>

Вы также можете изменить это поведение в любой момент времени в течение выполнения действия пользователем с помощью <code>setCompleteAutomatically(boolean)</code>.

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

Используется <code>addEventProperty</code> для прикрепления пользовательских данных к действию пользователя. Ключи свойств должны иметь префикс <code>event_properties.</code>. Свойства, добавленные после <code>complete()</code> вызова метода, игнорируются без уведомления.

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

'''Kotlin'''
<pre>
val userAction = Astromkey.createUserAction(
UserActionConfiguration("Процесс оформления заказа")
)

userAction.addEventProperty("event_properties.payment_method", "credit_card")
userAction.addEventProperty("event_properties.cart_value", 149.99)
userAction.addEventProperty("event_properties.item_count", 3)

// ... выполнить рабочий процесс ...

userAction.complete()
</pre>

'''Java'''
<pre>
UserAction userAction = Astromkey.createUserAction(
new UserActionConfiguration("Процесс оформления заказа")
);

userAction.addEventProperty("event_properties.payment_method", "credit_card");
userAction.addEventProperty("event_properties.cart_value", 149.99);
userAction.addEventProperty("event_properties.item_count", 3);

// ... выполнить рабочий процесс ...

userAction.complete();
</pre>

=== Пример: Процесс оформления заказа в интернет-магазине ===

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

'''Kotlin'''
<pre>
class CheckoutViewModel(
private val paymentRepository: PaymentRepository
) : ViewModel() {

private var checkoutAction: UserAction? = null

// Вызывается из пользовательского интерфейса, когда пользователь нажимает кнопку "Оформить заказ".
fun onCheckoutButtonClicked(cart: Cart) {
checkoutAction = Astromkey.createUserAction(
UserActionConfiguration("Процесс оформления заказа")
).apply {
addEventProperty("event_properties.cart_id", cart.id)
addEventProperty("event_properties.item_count", cart.items.size)
addEventProperty("event_properties.cart_total", cart.total)
addEventProperty("event_properties.currency", cart.currency)
}

processPayment(cart)
}

private fun processPayment(cart: Cart) {
viewModelScope.launch {
try {
val result = paymentRepository.processPayment(cart)
completeCheckout(orderId = result.orderId)
} catch (e: Exception) {
cancelCheckout(reason = e.message ?: "unknown_error")
}
}
}

private fun completeCheckout(orderId: String) {
checkoutAction?.let {
it.addEventProperty("event_properties.order_id", orderId)
it.addEventProperty("event_properties.checkout_successful", true)
it.complete()
}
checkoutAction = null
}

private fun cancelCheckout(reason: String) {
checkoutAction?.let {
it.addEventProperty("event_properties.checkout_successful", false)
it.addEventProperty("event_properties.cancellation_reason", reason)
it.complete()
}
checkoutAction = null
}
}
</pre>

'''Java'''
<pre>
public class CheckoutViewModel extends ViewModel {

private final PaymentRepository paymentRepository;
private UserAction checkoutAction = null;

public CheckoutViewModel(PaymentRepository paymentRepository) {
this.paymentRepository = paymentRepository;
}

// Вызывается из пользовательского интерфейса, когда пользователь нажимает кнопку "Оформить заказ".
public void onCheckoutButtonClicked(Cart cart) {
checkoutAction = Astromkey.createUserAction(
new UserActionConfiguration("Процесс оформления заказа")
);
checkoutAction.addEventProperty("event_properties.cart_id", cart.getId());
checkoutAction.addEventProperty("event_properties.item_count", cart.getItems().size());
checkoutAction.addEventProperty("event_properties.cart_total", cart.getTotal());
checkoutAction.addEventProperty("event_properties.currency", cart.getCurrency());

processPayment(cart);
}

private void processPayment(Cart cart) {
paymentRepository.processPayment(cart, new PaymentCallback() {
@Override
public void onSuccess(PaymentResult result) {
completeCheckout(result.getOrderId());
}

@Override
public void onError(String errorMessage) {
cancelCheckout(errorMessage != null ? errorMessage : "unknown_error");
}
});
}

private void completeCheckout(String orderId) {
if (checkoutAction != null) {
checkoutAction.addEventProperty("event_properties.order_id", orderId);
checkoutAction.addEventProperty("event_properties.checkout_successful", true);
checkoutAction.complete();
checkoutAction = null;
}
}

private void cancelCheckout(String reason) {
if (checkoutAction != null) {
checkoutAction.addEventProperty("event_properties.checkout_successful", false);
checkoutAction.addEventProperty("event_properties.cancellation_reason", reason);
checkoutAction.complete();
checkoutAction = null;
}
}
}
</pre>

Инструментарий для анализа действий пользователя - История изменений