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

Материал из Документация Ключ-АСТРОМ

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

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

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

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

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

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

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

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

Используется sendEvent() для создания отчетов о пользовательских событиях с необязательными параметрами продолжительности и свойствами события.

Основное использование

Swift 

// Простое событие
Astromkey.sendEvent(DTXEventData())

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

Objective-C 

// Простое событие
[Astromkey sendEvent:[[DTXEventData alloc] init]];

// Событие с указанием длительности (в миллисекундах)
[Astromkey sendEvent:[[[DTXEventData alloc] init] withDuration:@150]];

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

Добавьте пользовательские свойства для обеспечения контекста ваших событий. Ключи свойств должны начинаться с префикса event_properties..

Swift 

Astromkey.sendEvent(
    DTXEventData()
        .withDuration(250)
        .addEventProperty("event_properties.checkout_step", value: "payment_confirmed")
        .addEventProperty("event_properties.cart_value", value: 149.99)
        .addEventProperty("event_properties.item_count", value: 3)
)

Objective-C 

[Astromkey sendEvent:[[[[[DTXEventData alloc] init]
    withDuration:@250]
    addEventProperty:@"event_properties.checkout_step" value:@"payment_confirmed"]
    addEventProperty:@"event_properties.cart_value" value:@149.99]
    addEventProperty:@"event_properties.item_count" value:@3]];

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

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

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

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

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

Swift 

let subscriber = Astromkey.addEventModifier { event in
    // Добавить отслеживание экспериментов для всех событий
    event.fields["event_properties.experiment_id"] = "checkout_flow_v2"
    event.fields["event_properties.variant"] = "treatment_a"
    return event
}

Objective-C 

DTXModifyEventSubscriber *subscriber = [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
    // Добавить отслеживание экспериментов для всех событий
    event.fields[@"event_properties.experiment_id"] = @"checkout_flow_v2";
    event.fields[@"event_properties.variant"] = @"treatment_a";
    return event;
}];

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

Вернуться nil, чтобы отменить событие:

Swift 

let subscriber = Astromkey.addEventModifier { event in
    // Отфильтровывать события от тестовых пользователей
    if event.fields["event_properties.is_test_user"] as? Bool == true {
        return nil // Отбросить это событие
    }
    return event
}

Objective-C 

DTXModifyEventSubscriber *subscriber = [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
    // Отфильтровывать события от тестовых пользователей
    if ([event.fields[@"event_properties.is_test_user"] boolValue]) {
        return nil; // Отбросить это событие
    }
    return event;
}];

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

Swift 

let subscriber = Astromkey.addEventModifier { event in
    // Удаление идентификаторов пользователей из URL-адресов
    if let url = event.fields["url.full"] as? String {
        let redactedUrl = url.replacingOccurrences(
            of: #"/users/\w+/"#,
            with: "/users/{id}/",
            options: .regularExpression
        )
        event.fields["url.full"] = redactedUrl
    }
    return event
}

Objective-C 

DTXModifyEventSubscriber *subscriber = [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
    // Удаление идентификаторов пользователей из URL-адресов
    NSString *url = event.fields[@"url.full"];
    if (url) {
        NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern:@"/users/\\w+/" options:0 error:nil];
        NSString *redactedUrl = [regex stringByReplacingMatchesInString:url options:0 range:NSMakeRange(0, url.length) withTemplate:@"/users/{id}/"];
        event.fields[@"url.full"] = redactedUrl;
    }
    return event;
}];

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

Swift 

// Сохраняйте данные подписчика при добавлении модификатора
let subscriber = Astromkey.addEventModifier { event in
    event.fields["event_properties.custom"] = "value"
    return event
}

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

Objective-C 

// Сохраняйте данные подписчика при добавлении модификатора
DTXModifyEventSubscriber *subscriber = [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
    event.fields[@"event_properties.custom"] = @"value";
    return event;
}];

// Удалять, когда больше не требуется
[Astromkey removeEventModifier:subscriber];

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

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

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

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

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

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

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

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

Примеры модификаторов

Добавить контекст пользователя ко всем событиям

Swift 

class UserContext {
    static var userId: String?
    static var userTier: String?
}

func setupEventEnrichment() {
    _ = Astromkey.addEventModifier { event in
        if let userId = UserContext.userId {
            event.fields["event_properties.user_id_hash"] = userId.hashValue
        }
        if let userTier = UserContext.userTier {
            event.fields["event_properties.user_tier"] = userTier
        }
        return event
    }
}

Objective-C 

static NSString *userId = nil;
static NSString *userTier = nil;

- (void)setupEventEnrichment {
    [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
        if (userId) {
            event.fields[@"event_properties.user_id_hash"] = @(userId.hash);
        }
        if (userTier) {
            event.fields[@"event_properties.user_tier"] = userTier;
        }
        return event;
    }];
}

Добавить флаги функций

Swift 

func setupFeatureFlagTracking(featureFlags: [String: Bool]) {
    _ = Astromkey.addEventModifier { event in
        for (key, value) in featureFlags {
            event.fields["event_properties.ff_\(key)"] = value
        }
        return event
    }
}

Objective-C 

- (void)setupFeatureFlagTrackingWithFlags:(NSDictionary<NSString *, NSNumber *> *)featureFlags {
    [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
        for (NSString *key in featureFlags) {
            NSString *fieldKey = [NSString stringWithFormat:@"event_properties.ff_%@", key];
            event.fields[fieldKey] = featureFlags[key];
        }
        return event;
    }];
}

Условное обогащение событий

Swift 

func setupConditionalEnrichment() {
    _ = Astromkey.addEventModifier { event in
        // Обогащать только HTTP-события
        if event.fields["http.request.method"] != nil {
            event.fields["event_properties.api_client"] = "ios_app"
            event.fields["event_properties.api_version"] = "v2"
        }

        // Обогащать только события ошибок
        if event.fields["exception.type"] != nil {
            event.fields["event_properties.error_context"] = "user_session"
        }

        return event
    }
}

Objective-C 

- (void)setupConditionalEnrichment {
    [Astromkey addEventModifier:^DTXModifyableEvent *(DTXModifyableEvent *event) {
        // Обогащать только HTTP-события
        if (event.fields[@"http.request.method"]) {
            event.fields[@"event_properties.api_client"] = @"ios_app";
            event.fields[@"event_properties.api_version"] = @"v2";
        }

        // Обогащать только события ошибок
        if (event.fields[@"exception.type"]) {
            event.fields[@"event_properties.error_context"] = @"user_session";
        }

        return event;
    }];
}

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

  • Производительность веб-запросов — модификаторы HTTP-событий.
  • Сообщения об ошибках и сбоях — события исключений.
  • Конфигурация — конфигурация агента.
Источник — https://doc.ruscomtech.ru/index.php?title=Пользовательские_события_для_iOS&oldid=6596