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

2026-08-19T18:04:50Z

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

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

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

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

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