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

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

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

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

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

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

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

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

Нажмите на кнопку в com.example.MainActivity

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

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

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

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

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

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

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

Kotlin

Astromkey.setAutomaticUserActionDetection(false)

Java

Astromkey.setAutomaticUserActionDetection(false);

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

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

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

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

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

Kotlin

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

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

userAction.complete()

Java

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

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

userAction.complete();

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

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

Kotlin

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

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

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

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

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

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

Kotlin

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()

Java

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();

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

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

Kotlin

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
    }
}

Java

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;
        }
    }
}