Просмотр кода страницы Инструментарий для анализа действий пользователя для iOS

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

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

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

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

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

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

* '''Имя экрана''': Полное имя класса, в котором произошло касание, например, <code>ViewController</code> для '''UIKit''' или <code>ContentView</code> для '''SwiftUI'''. Если вы зададите пользовательское имя представления через API, будет использоваться именно это имя.
* '''Название элемента''': ЕдиныйАгент использует название типа компонента элемента, который обрабатывал выделение, например, <code>UIButton</code>.

'''коснитесь кнопки UIButton в ViewController'''

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

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

* '''UIKit''': Логика выполняется в методе <code>UIApplication</code> <code>sendEvent</code>.
* '''SwiftUI''': Логика выполняется либо через действие кнопки, либо через модификатор <code>onTapGesture</code>.

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

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

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

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

'''Swift'''
<pre>
Astromkey.setAutomaticUserActionDetectionEnabled(false)
</pre>

'''Objective-C'''
<pre>
[Astromkey setAutomaticUserActionDetectionEnabled:NO];
</pre>

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

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

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

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

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

'''Swift'''
<pre>
let userAction = Astromkey.createUserAction(configuration:
    DTXUserActionConfiguration(customName: "Процесс оформления заказа")
)

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

userAction.complete()
</pre>

'''Objective-C'''
<pre>
DTXUserActionConfiguration *configuration = [[DTXUserActionConfiguration alloc] initWithCustomName:@"Checkout Process"];
DTXUserAction *userAction = [Astromkey createUserActionWithConfiguration:configuration];

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

[userAction complete];
</pre>

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

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

'''Swift'''
<pre>
let userAction = Astromkey.createUserAction(configuration:
    DTXUserActionConfiguration(customName: "Процесс оформления заказа")
        .withCompleteAutomatically(true)
)

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

'''Objective-C'''
<pre>
DTXUserActionConfiguration *configuration = [[[DTXUserActionConfiguration alloc] initWithCustomName:@"Checkout Process"] withCompleteAutomatically:YES];
DTXUserAction *userAction = [Astromkey createUserActionWithConfiguration:configuration];

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

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

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

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

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

'''Swift'''
<pre>
let userAction = Astromkey.createUserAction(configuration:
    DTXUserActionConfiguration(customName: "Процесс оформления заказа")
)

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

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

userAction.complete()
</pre>

'''Objective-C'''
<pre>
DTXUserActionConfiguration *configuration = [[DTXUserActionConfiguration alloc] initWithCustomName:@"Checkout Process"];
DTXUserAction *userAction = [Astromkey createUserActionWithConfiguration:configuration];

[userAction addEventProperty:@"event_properties.payment_method" value:@"credit_card"];
[userAction addEventProperty:@"event_properties.cart_value" value:@(149.99)];
[userAction addEventProperty:@"event_properties.item_count" value:@(3)];

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

[userAction complete];
</pre>

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

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

'''Swift'''
<pre>
final class CheckoutViewController: UIViewController {

    // MARK: - Свойства

    private let cart: Cart
    private let paymentService: PaymentService

    private var checkoutAction: DTXUserAction?

    // MARK: - Частные методы

    @objc private func checkoutButtonTapped(_ sender: UIButton) {
        let configuration = DTXUserActionConfiguration(customName: "Checkout Process")
        checkoutAction = Astromkey.createUserAction(configuration: configuration)

        checkoutAction?.addEventProperty("event_properties.cart_id", value: cart.id)
        checkoutAction?.addEventProperty("event_properties.item_count", value: cart.items.count)
        checkoutAction?.addEventProperty("event_properties.cart_total", value: cart.total)
        checkoutAction?.addEventProperty("event_properties.currency", value: cart.currency)

        paymentService.processPayment(for: cart) { [weak self] result in
            switch result {
            case .success(let order):
                self?.completeCheckout(orderId: order.id)
            case .failure(let error):
                self?.cancelCheckout(reason: error.localizedDescription)
            }
        }
    }

    private func completeCheckout(orderId: String) {
        checkoutAction?.addEventProperty("event_properties.order_id", value: orderId)
        checkoutAction?.addEventProperty("event_properties.checkout_successful", value: true)
        checkoutAction?.complete()
        checkoutAction = nil
    }

    private func cancelCheckout(reason: String) {
        checkoutAction?.addEventProperty("event_properties.checkout_successful", value: false)
        checkoutAction?.addEventProperty("event_properties.cancellation_reason", value: reason)
        checkoutAction?.complete()
        checkoutAction = nil
    }
}
</pre>

'''Objective-C'''
<pre>
@interface CheckoutViewController ()

@property (nonatomic) Cart *cart;
@property (nonatomic) PaymentService *paymentService;
@property (nonatomic, nullable) DTXUserAction *checkoutAction;

@end

@implementation CheckoutViewController

- (void)checkoutButtonTapped:(UIButton *)sender {
    DTXUserActionConfiguration *configuration = [[DTXUserActionConfiguration alloc] initWithCustomName:@"Checkout Process"];
    self.checkoutAction = [Astromkey createUserActionWithConfiguration:configuration];

    [self.checkoutAction addEventProperty:@"event_properties.cart_id" value:self.cart.id];
    [self.checkoutAction addEventProperty:@"event_properties.item_count" value:@(self.cart.items.count)];
    [self.checkoutAction addEventProperty:@"event_properties.cart_total" value:self.cart.total];
    [self.checkoutAction addEventProperty:@"event_properties.currency" value:self.cart.currency];

    __weak typeof(self) weakSelf = self;
    [self.paymentService processPaymentForCart:self.cart completion:^(Order *order, NSError *error) {
        if (order) {
            [weakSelf completeCheckoutWithOrderId:order.id];
        } else {
            [weakSelf cancelCheckoutWithReason:error.localizedDescription];
        }
    }];
}

- (void)completeCheckoutWithOrderId:(NSString *)orderId {
    [self.checkoutAction addEventProperty:@"event_properties.order_id" value:orderId];
    [self.checkoutAction addEventProperty:@"event_properties.checkout_successful" value:@YES];
    [self.checkoutAction complete];
    self.checkoutAction = nil;
}

- (void)cancelCheckoutWithReason:(NSString *)reason {
    [self.checkoutAction addEventProperty:@"event_properties.checkout_successful" value:@NO];
    [self.checkoutAction addEventProperty:@"event_properties.cancellation_reason" value:reason];
    [self.checkoutAction complete];
    self.checkoutAction = nil;
}

@end
</pre>