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

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

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

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

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

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

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

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

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

Пользовательские события отправляются с помощью Astromkey.sendEvent(...) с использованием необязательных свойств продолжительности и самого события.

Рассмотрите базовое использование.

Kotlin

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

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

Java

// Простое событие
Astromkey.sendEvent(new EventData());

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

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

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

Kotlin

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

Java

Astromkey.sendEvent(new EventData()
    .withDuration(250)
    .addEventProperty("event_properties.checkout_step", "payment_confirmed")
    .addEventProperty("event_properties.cart_value", 149.99)
    .addEventProperty("event_properties.item_count", 3)
);

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

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

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

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

На Android модификаторы работают с представлением события в виде JSONObject.

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

Kotlin

val modifier = EventModifier { event ->
    // Добавить контекст варианта сборки ко всем событиям
    event.put("event_properties.build_type", BuildConfig.BUILD_TYPE)
    event.put("event_properties.flavor", BuildConfig.FLAVOR)
    event
}

Astromkey.addEventModifier(modifier)

Java

EventModifier modifier = (JSONObject event) -> {
    // Добавить контекст варианта сборки ко всем событиям
    event.put("event_properties.build_type", BuildConfig.BUILD_TYPE);
    event.put("event_properties.flavor", BuildConfig.FLAVOR);
    return event;
};

Astromkey.addEventModifier(modifier);

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

Возврат null отменяет событие.

Kotlin

val modifier = EventModifier { event ->
    // События, происходящие в активности com.example.MainActivity, будут отброшены.
    if (event.optString("view.detected_name") == "com.example.MainActivity") {
        return@EventModifier null
    }
    event
}

Astromkey.addEventModifier(modifier)

Java

EventModifier modifier = (JSONObject event) -> {
    // События, происходящие в активности com.example.MainActivity, будут отброшены.
    if ("com.example.MainActivity".equals(event.optString("view.detected_name"))) {
        return null;
    }
    return event;
};

Astromkey.addEventModifier(modifier);

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

Kotlin

val modifier = EventModifier { event ->
    // Удаление идентификаторов пользователей из URL-адресов
    val url = event.optString("url.full", null)
    if (url != null) {
        val redactedUrl = url.replace(Regex("/users/\\w+/"), "/users/{id}/")
        event.put("url.full", redactedUrl)
    }
    event
}

Astromkey.addEventModifier(modifier)

Java

EventModifier modifier = (JSONObject event) -> {
    // Удаление идентификаторов пользователей из URL-адресов
    String url = event.optString("url.full", null);
    if (url != null) {
        String redactedUrl = Pattern.compile("/users/\\w+/")
            .matcher(url)
            .replaceAll("/users/{id}/");
        event.put("url.full", redactedUrl);
    }
    return event;
};

Astromkey.addEventModifier(modifier);

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

Kotlin

// Сохраните модификатор при его добавлении
val modifier = EventModifier { event ->
    event.put("event_properties.custom", "value")
    event
}

Astromkey.addEventModifier(modifier)

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

Java

// Сохраните модификатор при его добавлении
EventModifier modifier = (JSONObject event) -> {
    event.put("event_properties.custom", "value");
    return event;
};

Astromkey.addEventModifier(modifier);

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

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

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

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

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

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

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

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

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

Пример модификатора: условное обогащение событий

Следующий пример демонстрирует, как обогащать информацию только для определенных типов событий. Он добавляет контекст к HTTP-событиям (для сегментации API) и к событиям ошибок (для более быстрой обработки).

Kotlin

fun setupConditionalEnrichment(apiClientName: String) {
    val modifier = EventModifier { event ->
        // Добавлять контекст только для HTTP-событий
        if (event.optBoolean("characteristics.has_request")) {
            event.put("event_properties.api_client", apiClientName)
            event.put("event_properties.api_kind", "backend")
        }

        // Добавлять контекст только для событий ошибок
        if (event.optBoolean("characteristics.has_error")) {
            event.put("event_properties.triage_owner", "mobile")
            event.put("event_properties.triage_severity", "error")
        }

        event
    }

    Astromkey.addEventModifier(modifier)
}

Java

public void setupConditionalEnrichment(final String apiClientName) {
    EventModifier modifier = (JSONObject event) -> {
        // Добавлять контекст только для HTTP-событий
        if (event.optBoolean("characteristics.has_request")) {
            event.put("event_properties.api_client", apiClientName);
            event.put("event_properties.api_kind", "backend");
        }

        // Добавлять контекст только для событий ошибок
        if (event.optBoolean("characteristics.has_error")) {
            event.put("event_properties.triage_owner", "mobile");
            event.put("event_properties.triage_severity", "error");
        }

        return event;
    };

    Astromkey.addEventModifier(modifier);
}

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

• Производительность веб-запросов — модификаторы HTTP-событий.
• Сообщения об ошибках и сбоях — события исключений.
• Конфигурация — конфигурация агента.