Инструментирование с помощью ЕдиныйАгент SDK для Android

Используйте ЕдиныйАгент SDK для Android, чтобы сообщать дополнительные сведения о сеансах пользователей в своем мобильном приложении. ЕдиныйАгент SDK для Android позволяет создавать настраиваемые действия, сообщать об ошибках, отмечать конкретных пользователей и т. д. В разделах ниже объясняется, как включить эти возможности.

Вы можете использовать ЕдиныйАгент SDK в Java и Kotlin.

Запустить ЕдиныйАгент

Если вы отключили автоматический запуск с помощью autoStart.enabledсвойства или используете автономное ручное инструментирование вместо автоматического, запустите ЕдиныйАгент вручную в Application.onCreateметоде. Используйте astromkey.startup(Application, Configuration)метод API.

Java:

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // provide the application context as parameter
        astromkey.startup(this, new astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration());
    }
}

Kotlin:

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        // provide the application context as parameter
        astromkey.startup(this, astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration())
    }
}

Если вам нужно запустить ЕдиныйАгент на более позднем этапе, используйте astromkey.startup(Activity, Configuration)метод API. Вы должны предоставить актив Activityв качестве параметра, чтобы ЕдиныйАгент мог немедленно отслеживать его.

Java:

astromkey.startup(yourActiveActivity, new astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
  ... // additional configuration
  .buildConfiguration());

Kotlin:

astromkey.startup(yourActiveActivity, astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
  ... // additional configuration
  .buildConfiguration())

Запустите ЕдиныйАгент в ЕдиныйАгент для Android версии 8.229 и более ранних версий.

ЕдиныйАгент для Android версии 8.229 и более ранних версий

Если вы отключили автоматический запуск с помощью autoStart.enabledсвойства или используете автономное ручное инструментирование вместо автоматического, запустите ЕдиныйАгент вручную в Application.onCreateметоде.

Java:

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        astromkey.startup(this, new astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration());
    }
}

Kotlin:

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        astromkey.startup(this, astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration())
    }
}

Если ваше приложение поддерживает прямую загрузку, убедитесь, что astromkey.startupоно никогда не вызывается из компонента, поддерживающего прямую загрузку. Также см. раздел Настройка связи с ЕдиныйАгент SDK для Android , чтобы убедиться, что ЕдиныйАгент может передавать данные в кластер Ключ-АСТРОМ.

Настроить ЕдиныйАгент

Используйте класс astromkeyConfigurationBuilder для настройки параметров ЕдиногоАгента.

Java:

new astromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withUserOptIn(true)
    .withCrashReporting(true)
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withUserOptIn(true)
    .withCrashReporting(true)
    .buildConfiguration()

Если вы используете комбинацию ручного и автоматического инструментирования, автоматическое инструментирование вводит вызов Astromkey.startupв Application.onCreateметод. В этом случае введенный Astromkey.startupвызов вызывается перед вашим ручным Astromkey.startupвызовом, поэтому ваша ручная настройка игнорируется.

Используйте это autoStart.enabledсвойство, чтобы деактивировать функцию автозапуска из автоинструментации. Затем вы можете определить ручной Astromkey.startupвызов . В этом случае вы можете переопределить значения, предварительно настроенные из автоинструментации.

Мониторинг действий пользователя

С помощью мониторинга действий пользователя вы можете определять и сообщать о пользовательских действиях. Затем вы можете дополнить эти настраиваемые действия, используя следующие операции мониторинга:

• Создать дочернее действие
• Сообщить о событии
• Сообщить значение
• Сообщить об ошибке
• Прикрепите веб-запрос к действию пользователя

Пользовательские действия отличаются от действий пользователя, созданных с помощью плагина Astromkey для Android Gradle. ЕдиныйАгент не добавляет автоматически дополнительные события, такие как веб-запросы, в настраиваемые действия или закрытие настраиваемых действий. Однако, когда ЕдиныйАгент завершает работу или должен начать новый сеанс, он закрывает все открытые дополнительные действия.

Создание настраиваемых действий

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

Вызов enterActionдля запуска пользовательского действия и leaveActionзакрытия пользовательского действия. Время измеряется автоматически.

Java:

// start a custom action
DTXAction action = Astromkey.enterAction("Tap on Search");

// ...do some work here...

// end a custom action
action.leaveAction();

Kotlin:

// start a custom action
val action = Astromkey.enterAction("Tap on Search")

// ...do some work here...

// end a custom action
action.leaveAction()

Для пользовательского мобильного действия или мобильного действия пользователя, сгенерированного автоматически, максимальная длина имени составляет 250 символов.

Максимальная продолжительность пользовательского действия для мобильных устройств составляет 9 минут.

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

Создание дочерних действий

Дочерние действия аналогичны родительским действиям. Когда родительское действие закрывается, ЕдиныйАгент автоматически закрывает все дочерние действия родительского действия.

Создайте дочерние действия с помощью Astromkey.enterAction(String, DTXAction)метода.

Java:

// start a parent custom action
DTXAction parentAction = Astromkey.enterAction("Tap on Search");

// ...do some work here...

// start a child action
DTXAction childAction = Astromkey.enterAction("Tap on Confirm", parentAction);

// ...do some work here...

// end a child action
childAction.leaveAction();

// ...do some work here...

// end a parent custom action
parentAction.leaveAction();

Kotlin:

// start a parent custom action
val parentAction = Astromkey.enterAction("Tap on Search")

// ...do some work here...

// start a child action
val childAction = Astromkey.enterAction("Tap on Confirm", parentAction)

// ...do some work here...

// end a child action
childAction.leaveAction()

// ...do some work here...

// end a parent custom action
parentAction.leaveAction()

Для пользовательского мобильного действия или мобильного действия пользователя, сгенерированного автоматически, максимальная длина имени составляет 250 символов.

Отменить дополнительные действия

ЕдиныйАгент для Android версии 8.231+

Если вам нужно отменить уже созданное, но еще не выполненное пользовательское действие, используйте DTXAction#cancel()вызов API.

При отмене действия удаляются все связанные с ним данные: все сообщаемые значения отбрасываются, а все дочерние действия отменяются. Также обратите внимание, что вы не можете отменить завершенное действие.

Java:

// create a custom action
DTXAction action = Astromkey.enterAction("Tap on Purchase");
try {
    // ...do some work here...
    performWork();

    // close the custom action. All associated data is stored and sent to Astromkey
    action.leaveAction();
}
catch(Exception e) {
    // cancel the custom action. All associated data is discarded.
    action.cancel();
}

Kotlin:

// create a custom action
val action = Astromkey.enterAction("Tap on Purchase")
try {
    // ...do some work here...
    performWork()

    // close the custom action. All associated data is stored and sent to Astromkey
    action.leaveAction()
} catch (e: Exception) {
    // cancel the custom action. All associated data is discarded.
    action.cancel()
}

Определить состояние пользовательского действия

ЕдиныйАгент для Android версии 8.231+

Иногда полезно знать, открыто ли пользовательское действие и может ли оно использоваться для отчета о данных.

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

Пользовательское действие завершается, когда оно:

• Завершено через DTXAction#leaveAction(), или
• Отменено через DTXAction#cancel(), или
• Прервано ЕдинымАгентом(например, при завершении работы ЕдиногоАгента)

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

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

В следующем фрагменте кода показан пример инструментирования вымышленного метода поиска, который отправляет веб-запрос на инструментированный сервер и анализирует полученный результат. Следующие инструментальные действия являются частью фрагмента кода:

1. Создает пользовательское действие
2. Сообщает значение
3. Сообщает об ошибке
4. Отслеживает веб-запрос
5. Создает дочернее действие

Java:

public boolean search(String query) {
    // [1a] start a parent custom action
    DTXAction searchAction = Astromkey.enterAction("Tap on Search");

    // [2] report a value
    searchAction.reportValue("query", query);

    URL url;
    try {
        url = new URL("https://www.example.com/?query=" + query);
    } catch (MalformedURLException e) {
        // [3] report an error
        searchAction.reportError("invalid url", e);

        // [1b] end a parent custom action
        searchAction.leaveAction();
        return false;
    }

    // [4.1] Generate a new unique tag associated with the custom action "Tap on Search"
    String uniqueRequestTag = searchAction.getRequestTag();
    // [4.2] Generate a WebRequestTiming object based on the unique tag
    WebRequestTiming timing = Astromkey.getWebRequestTiming(uniqueRequestTag);

    Request request = new Request.Builder()
            .url(url)
            // [4.3] Place the Astromkey HTTP header on your web request
            .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
            .build();

    // [4.4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming();
    try (Response response = client.newCall(request).execute()) {
        if (!response.isSuccessful()) {
            // [4.5] Stop web request timing when a connection exception occurs
            timing.stopWebRequestTiming(url, response.code(), response.message());
            return false;
        }
        String body = response.body().string();

        // [4.5] Stop web request timing when the HTTP response is received and the response body is obtained
        timing.stopWebRequestTiming(url, response.code(), response.message());

        // [5a] start a child action
        DTXAction parseAction = Astromkey.enterAction("Parse result", searchAction);

        parseResult(body);

        // [5b] end a child action
        parseAction.leaveAction();

        return true;
    } catch (IOException e) {
        // [4.5] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString());

        return false;
    }
    finally {
        // [1b] end a parent custom action
        searchAction.leaveAction();
    }
}

Kotlin:

fun search(query: String): Boolean {
    // [1a] start a parent custom action
    val searchAction = Astromkey.enterAction("Tap on Search")

    // [2] report a value
    searchAction.reportValue("query", query)

    var url: URL? = null
    try {
        url = URL("https://www.example.com/?query=$query")
    } catch (e: MalformedURLException) {
        // [3] report an error
        searchAction.reportError("invalid url", e)

        // [1b] end a parent custom action
        searchAction.leaveAction()
        return false
    }

    // [4.1] Generate a new unique tag associated with the custom action "Tap on Search"
    val uniqueRequestTag = searchAction.requestTag
    // [4.2] Generate a WebRequestTiming object based on the unique tag
    val timing = Astromkey.getWebRequestTiming(uniqueRequestTag)

    val request = Request.Builder()
        .url(url)
        // [4.3] Place the Astromkey HTTP header on your web request
        .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
        .build()

    try {
        // [4.4] Start web request timing before the HTTP request is sent
        timing.startWebRequestTiming()
        client.newCall(request).execute().use { response ->
            if (!response.isSuccessful) {
                // [4.5] Stop web request timing when a connection exception occurs
                timing.stopWebRequestTiming(url, response.code, response.message)
                return false
            }
            val body = response.body!!.string()

            // [4.5] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code, response.message)

            // [5a] start a child action
            val parseAction = Astromkey.enterAction("Parse result", searchAction)

            parseResult(body)

            // [5b] end a child action
            parseAction.leaveAction()
        }

        return true
    } catch (e: IOException) {
        // [4.5] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString())

        return false
    } finally {
        // [1b] end a parent custom action
        searchAction.leaveAction()
    }
}

Отчеты о пользовательских значениях

Используя ЕдиныйАгент SDK для Android, вы можете сообщать о событиях, значениях и ошибках. Сообщенные события, значения и ошибки, которые являются частью действия пользователя, затем отображаются в каскадном анализе действий пользователя. Сообщенные ошибки (как отдельные, так и «прикрепленные» к действию пользователя) также отображаются на странице сведений о сеансе пользователя и многомерной странице анализа действий пользователя .

Сообщить о событии

С помощью reportEventвы можете сообщить о конкретном событии. Сообщаемое событие должно быть частью действия пользователя.

Java:

action.reportEvent("event_name");

Kotlin:

action.reportEvent("event_name")

Если вы хотите сообщать об отдельных событиях с большим количеством дополнительной информации, см. раздел Отчеты о бизнес-событиях .

Сообщить значение

Метод reportValueпозволяет вам сообщать свои собственные показатели. Эти показатели должны быть частью действия пользователя.

ЕдиныйАгент SDK позволяет сообщать показатели со следующими типами значений:

• int
• long
• double
• string

Метрики с типом longподдерживаются для ЕдиныйАгент SDK версии 8.197+.

Java:

// report int
action.reportValue("int_metrics_name", 5);
// report long
action.reportValue("long_metrics_name", 5L);
// report double
action.reportValue("double_metrics_name", 5.6);
// report string
action.reportValue("string_metrics_name", "exampleValue");

Kotlin:

// report int
action.reportValue("int_metrics_name", 5)
// report long
action.reportValue("long_metrics_name", 5L)
// report double
action.reportValue("double_metrics_name", 5.6)
// report string
action.reportValue("string_metrics_name", "exampleValue")

Сообщить об ошибке

Метод reportErrorотличается от reportValueметода, поскольку он конкретно идентифицируется как событие типа ошибки.

ЕдиныйАгент SDK позволяет вам сообщать о следующем:

• Коды ошибок . Используйте reportError(String, int)метод.
• Обработанные исключения . Используйте reportError(String, Throwable)метод.

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

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

Java:

// report an error code
action.reportError("error_code_name", -1);
// report an exception
action.reportError("exception_name", exception);

Kotlin:

// report an error code
action.reportError("error_code_name", -1)
// report an exception
action.reportError("exception_name", exception)

Автономная ошибка

Вы можете сообщать об отдельных событиях ошибок через Astromkeyкласс.

Java:

// report an error code
Astromkey.reportError("error_code_name", -1);
// report an exception
Astromkey.reportError("exception_name", exception);

Kotlin:

// report an error code
Astromkey.reportError("error_code_name", -1)
// report an exception
Astromkey.reportError("exception_name", exception)

Отчет о бизнес-событиях

ЕдиныйАгент для Android версии 8.253+

С помощью sendBizEventвы можете сообщать о деловых событиях. Это автономные события, поскольку ЕдиныйАгент отправляет их отдельно от действий пользователя или сеансов пользователя.

Дополнительные сведения о бизнес-событиях см. в разделе Бизнес-аналитика в Astromkey .

Java:

JSONObject attributes = new JSONObject();
try {
    attributes.put("event.name", "Confirmed Booking");
    attributes.put("screen", "booking-confirmation");
    attributes.put("product", "Danube Anna Hotel");
    attributes.put("amount", 358.35);
    attributes.put("currency", "USD");
    attributes.put("reviewScore", 4.8);
    attributes.put("arrivalDate", "2022-11-05");
    attributes.put("departureDate", "2022-11-15");
    attributes.put("journeyDuration", 10);
    attributes.put("adultTravelers", 2);
    attributes.put("childrenTravelers", 0);

    Astromkey.sendBizEvent("com.easytravel.funnel.booking-finished", attributes);
} catch (JSONException e) {
    // handle exception
}

Kotlin:

try {
    JSONObject().apply {
        put("event.name", "Confirmed Booking")
        put("screen", "booking-confirmation")
        put("product", "Danube Anna Hotel")
        put("amount", 358.35)
        put("currency", "USD")
        put("reviewScore", 4.8)
        put("arrivalDate", "2022-11-05")
        put("departureDate", "2022-11-15")
        put("journeyDuration", 10)
        put("adultTravelers", 2)
        put("childrenTravelers", 0)
    }.also { jsonObject->
        Astromkey.sendBizEvent("com.easytravel.funnel.booking-finished", jsonObject)
    }
} catch (e: JSONException) {
    // handle exception
}

Мониторинг жизненного цикла

ЕдиныйАгент для Android версии 8.223+

При мониторинге жизненного цикла ЕдиныйАгент собирает следующие данные:

• Отображение активности : измеряет временной интервал от Activity.onCreate(Bundle)до Activity.onPostResume()и сообщает время каждого введенного состояния жизненного цикла активности.
• Повторное отображение действия : измеряет время, необходимое для повторного отображения ранее созданного действия, и сообщает время каждого состояния жизненного цикла действия, которое было введено до тех пор, пока действие снова не станет видимым.

Мониторинг жизненного цикла активности включен по умолчанию, но вы можете отключить его с помощью withActivityMonitoringметода.

Java:

new AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withActivityMonitoring(false)
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withActivityMonitoring(false)
    .buildConfiguration()

Мониторинг веб-запросов

Плагин Astromkey для Android Gradle автоматически обрабатывает большинство веб-запросов. Однако вам придется вручную обрабатывать запросы в следующих случаях:

• Когда запросы стороннего фреймворка не инструментированы
• Когда вам нужно сообщать о запросах, отличных от HTTP(S)
• Если вы отключили мониторинг веб-запросов

Для запросов HTTP(S) никогда не сочетайте автоматическую и ручную инструментацию веб-запросов. Однако вы можете использовать автоматическое инструментирование для HTTP(S)-запросов и ручное инструментирование для не-HTTP(S)-запросов .

Чтобы отслеживать веб-запросы, добавьте x-astromkeyзаголовок HTTP с уникальным значением в веб-запрос. Это необходимо для сопоставления данных мониторинга на стороне сервера с соответствующим мобильным веб-запросом. Кроме того, необходимо измерить значения синхронизации с мобильной стороны.

Мониторинг веб-запроса

1. Создайте новый уникальный тег.
2. Создайте WebRequestTimingобъект на основе тега.
3. Поместите HTTP-заголовок Astromkey в свой веб-запрос.
4. Начать отсчет времени веб-запроса до отправки HTTP-запроса.
5. Остановить синхронизацию веб-запросов.
   • Получен HTTP-ответ и тело ответа.
   • Возникает исключение соединения.

Существует два типа веб-запросов с точки зрения их иерархии:

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

Прикрепите веб-запрос к действию пользователя

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

В следующем примере показано, как присоединить синхронный OkHttpвеб-запрос к "Search request"действию пользователя.

Java:

URL url = new URL("https://www.example.com");

// First, create a custom action
DTXAction webAction = Astromkey.enterAction("Search request");
// [1] Generate a new unique tag associated with the user action
String uniqueRequestTag = webAction.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = Astromkey.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request. This varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Astromkey HTTP header on your web request
        .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Start web request timing before the HTTP request is sent
timing.startWebRequestTiming();
try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        // handle response
        String body = response.body().string();
    }

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming(url, response.code(), response.message());
} catch (IOException e) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString());

    // user-defined exception handling
}
finally {
    // Lastly, end the custom action
    webAction.leaveAction();
}

Kotlin:

val url = URL("https://www.example.com")

// First, create a custom action
val webAction = Astromkey.enterAction("Search request")
// [1] Generate a new unique tag associated with the user action
val uniqueRequestTag = webAction.requestTag
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Astromkey.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request. This varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Astromkey HTTP header on your web request
    .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
    .build()

try {
    // [4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming()
    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // handle response
            val body = response.body!!.string()
        }

        // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
        timing.stopWebRequestTiming(url, response.code, response.message)
    }
} catch (e: IOException) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString())

    // user-defined exception handling
} finally {
    // Lastly, end the custom action
    webAction.leaveAction()
}

Прикрепите асинхронный веб-запрос OkHttp к действию пользователя.

Java:

final URL url = new URL("https://www.example.com");

// First, create a custom action
final DTXAction webAction = Astromkey.enterAction("Search request");
// [1] Generate a new unique tag associated with the user action
String uniqueRequestTag = webAction.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
final WebRequestTiming timing = Astromkey.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request. This varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Astromkey HTTP header on your web request
        .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Call startWebRequestTiming to begin the timing, and then handle the response body from the OkHttp call
timing.startWebRequestTiming();
client.newCall(request).enqueue(new Callback() {
    @Override
    public void onFailure(Call call, IOException e) {
        // [5.2] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString());

        // user-defined exception handling

        // [8] Lastly, end the custom action
        webAction.leaveAction();
    }

    @Override
    public void onResponse(Call call, Response response) throws IOException {
        try (ResponseBody responseBody = response.body()) {
            if (response.isSuccessful()) {
                // handle response
                String body = response.body().string();
            }

            // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code(), response.message());

            // Lastly, end the custom action
            webAction.leaveAction();
        }
    }
});

Kotlin:

val url = URL("https://www.example.com")

// First, create a custom action
val webAction = Astromkey.enterAction("Search request")
// [1] Generate a new unique tag associated with the user action
val uniqueRequestTag = webAction.requestTag
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Astromkey.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request. This varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Astromkey HTTP header on your web request
    .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
    .build()

// [4] Call startWebRequestTiming to begin the timing, and then handle the response body from the OkHttp call
timing.startWebRequestTiming()
client.newCall(request).enqueue(objectq: Callback {
    override fun onFailure(call: Call, e: IOException) {
        // [5.2] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString())

        // user-defined exception handling

        // [8] Lastly, end the custom action
        webAction.leaveAction()
    }

    @Throws(IOException::class)
    override fun onResponse(call: Call, response: Response) {
        response.use {
            if (response.isSuccessful) {
                // handle response
                val body = response.body!!.string()
            }

            // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code, response.message)

            // Lastly, end the custom action
            webAction.leaveAction()
        }
    }
})

Мониторинг автономного веб-запроса

Чтобы отслеживать веб-запрос как отдельный запрос, создайте уникальный тег с помощью Astromkey.getRequestTag()метода.

В следующем примере показано, как отслеживать синхронный OkHttpвеб-запрос.

Java:

URL url = new URL("https://www.example.com");

// [1] Generate a new unique tag
String uniqueRequestTag = Astromkey.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = Astromkey.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request. This varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Astromkey HTTP header on your web request
        .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Start web request timing before the HTTP request is sent
timing.startWebRequestTiming();
try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        // handle response
        String body = response.body().string();
    }

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming(url, response.code(), response.message());
} catch (IOException e) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString());

    // user-defined exception handling
}

Kotlin:

val url = URL("https://www.example.com")

// [1] Generate a new unique tag
val uniqueRequestTag = Astromkey.getRequestTag()
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Astromkey.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request. This varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Astromkey HTTP header on your web request
    .addHeader(Astromkey.getRequestTagHeader(), uniqueRequestTag)
    .build()

try {
    // [4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming()
    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // handle response
            val body = response.body!!.string()
        }

        // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
        timing.stopWebRequestTiming(url, response.code, response.message)
    }
} catch (e: IOException) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString())

    // user-defined exception handling
}

Мониторинг запросов, отличных от HTTP(S)

ЕдиныйАгент для Android версии 8.249+

Мониторинг соединений WebSocket доступен начиная с ЕдиногоАгента для Android версии 8.239. Мониторинг всех не-HTTP(S) запросов доступен начиная с ЕдиногоАгента для Android версии 8.249.

ЕдиныйАгент для Android не поддерживает автоматическую обработку запросов, отличных от HTTP(S). Если вам нужно сообщить о таких запросах, как запрос WebSocket (начинается с ws://или wss://), проверьте приведенные ниже примеры кода.

• Используйте stopWebRequestTiming(URI requestUri, int respCode, String respPhrase)метод API для ручной обработки запросов, отличных от HTTP(S).
• Обязательно передайте исходный URI. Не извлекайте URI из OkHttpобъекта, так как это не возвращает исходный URI.
• Этот подход подходит только для соединений WebSocket, которые открыты примерно до 9 минут. О более длительных соединениях может не сообщаться.
• Если у вас есть только не-HTTP(S) запросы, вы можете при желании отключить мониторинг веб-запросов .
• Если у вас есть как HTTP(S), так и не-HTTP(S) запросы, и HTTP(S) запросы автоматически инструментируются, не отключайте мониторинг веб-запросов.

Java:

final URI uri = URI.create("wss://websocket.example.com");

// First, create a custom action
DTXAction webSocketAction = Astromkey.enterAction("WebSocket");
// Generate a WebRequestTiming object based on the unique request tag
WebRequestTiming timing = Astromkey.getWebRequestTiming(webSocketAction.getRequestTag());
// Define your OkHttp request. This varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(uri.toString())
        .build();

// Start web request timing when you are about to open a WebSocket connection
timing.startWebRequestTiming();

WebSocket webSocket = client.newWebSocket(request, new WebSocketListener() {
    @Override
    public void onClosing(@NonNull WebSocket webSocket, int code, @NonNull String reason) {
        // Stop web request timing when the webSocket connection closes
        // Don't retrieve the URI from the OkHttp object because it always replaces wss:// with https://
        timing.stopWebRequestTiming(uri, code, reason);
        // end the action
        webSocketAction.leaveAction();
    }

    @Override
    public void onFailure(@NonNull WebSocket webSocket, @NonNull Throwable t, @Nullable Response response) {
        // Stop web request timing when the webSocket connection fails and customize the return code and message
        // Don't retrieve the URI from the OkHttp object because it always replaces wss:// with https://
        timing.stopWebRequestTiming(uri, 1011, "ERROR");
        // end the action
        webSocketAction.leaveAction();
    }
});

Kotlin:

val uri = URI.create("wss://websocket.example.com")
// First, create a custom action
val webSocketAction = Astromkey.enterAction("WebSocket")
// Generate a WebRequestTiming object based on the unique request tag
val webRequestTiming = Astromkey.getWebRequestTiming(webSocketAction.requestTag)
// Define your OkHttp request. This varies greatly depending on your implementation
val request = Request.Builder()
        .url(uri.toString())
        .build()

// Start web request timing when you are about to open a WebSocket connection
webRequestTiming.startWebRequestTiming()

val webSocket = client.newWebSocket(request, objectq: WebSocketListener() {
    override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
        // Stop web request timing when the webSocket connection closes
        // Don't retrieve the URI from the OkHttp object because it always replaces wss:// with https://
        webRequestTiming.stopWebRequestTiming(uri, code, reason)
        // end the action
        webSocketAction.leaveAction()
    }

    override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
        // Stop web request timing when the webSocket connection fails
        // Don't retrieve the URI from the OkHttp object because it always replaces wss:// with https://
        webRequestTiming.stopWebRequestTiming(uri, 1011, "ERROR")
        // end the action
        webSocketAction.leaveAction()
    }
})

Отчеты о сбоях

ЕдиныйАгент фиксирует все необработанные исключения и ошибки и немедленно отправляет отчет о сбое на сервер. Отчет о сбое Android включает время возникновения и полную трассировку стека исключения.

Вы можете отключить отчеты о сбоях, используя withCrashReportingметод:

Java:

new AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withCrashReporting(false)
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withCrashReporting(false)
    .buildConfiguration()

Отметить конкретных пользователей

Вы можете пометить каждого пользователя своих мобильных приложений уникальным именем пользователя. Это позволяет вам искать и фильтровать определенные сеансы пользователей и анализировать поведение отдельных пользователей с течением времени.

Следующие шаги объясняют, как пометить отдельного пользователя с помощью Ключ-АСТРОМ API.

Java:

Astromkey.identifyUser("john.doe@example.com");

Kotlin:

Astromkey.identifyUser("john.doe@example.com")

ЕдиныйАгент для Android версии 237+

ЕдиныйАгент для Android версии 237+Сеансы, разделенные из-за простоя или тайм-аута продолжительности, автоматически повторно помечаются.

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

Однако обратите внимание, что ЕдиныйАгент не повторно помечает последующий сеанс в следующих случаях:

• Когда вы явно завершаете помеченный пользовательский сеанс черезendVisit
• Когда пользователь или мобильная операционная система закрывает или принудительно останавливает приложение
• Когда ЕдиныйАгент завершает текущий сеанс пользователя и создает новый сеанс после изменения настроек конфиденциальности.

См. Сеансы пользователей > Завершение сеанса , чтобы узнать, когда ЕдиныйАгент завершает сеанс мобильного пользователя.

Завершить сеанс

Вы можете принудительно завершить сеанс с помощью Ключ-АСТРОМ API. Это также закрывает все открытые действия и запускает новый сеанс.

Java:

Astromkey.endVisit();

Kotlin:

Astromkey.endVisit()

Настроить конфиденциальность данных

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

Чтобы активировать режим согласия пользователя, включите userOptInфлаг через DSL из плагина Astromkey Android Gradle или используйте ConfigurationBuilder.withUserOptInметод.

С помощью этого Astromkey.applyUserPrivacyOptionsметода вы можете настроить параметры конфиденциальности в зависимости от решения пользователя.

Java:

Astromkey.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    .build()
);

Kotlin:

Astromkey.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    .build()
)

ЕдиныйАгент сохраняет настройки конфиденциальности и автоматически применяет их при перезапуске приложения. Кроме того, ЕдиныйАгент создает новый сеанс всякий раз, когда параметры конфиденциальности изменяются с помощью этого Astromkey.applyUserPrivacyOptionsметода.

Вы также можете получить настройки конфиденциальности с помощью Astromkey.getUserPrivacyOptionsметода. Однако этот метод следует использовать после запуска ЕдиногоАгента.

Конфиденциальность данных в ЕдиномАгенте для Android версии 8.189 и более ранних:

ЕдиныйАгент для Android версии 8.189 и более ранних версий

С помощью этого Astromkey.setCrashReportingOptedIn(boolean)метода вы можете активировать или деактивировать отчеты о сбоях. Уровень сбора данных можно изменить с помощью Astromkey.setDataCollectionLevel(DataCollectionLevel)метода.

Вы можете получить настройки конфиденциальности с помощью методов Astromkey.getDataCollectionLevel()и Astromkey.isCrashReportingOptedIn(). Используйте методы API конфиденциальности после запуска ЕдиногоАгента.

Настройка гибридных приложений

Для гибридных приложений, использующих RUM JavaScript внутри WebView(Android) или WKWebView(iOS), файлы cookie должны быть установлены для каждого инструментированного домена или сервера, с которым взаимодействует приложение. Когда функция мониторинга гибридных приложений включена, ЕдиныйАгент создает эти файлы cookie для каждого указанного домена и сохраняет их в файлах CookieManager.

Включить мониторинг гибридных приложений

Вы можете активировать функцию мониторинга гибридных приложений с помощью withHybridMonitoringметода. Укажите все используемые домены, хосты и IP-адреса с помощью метода withMonitoredDomainsили withMonitoredHttpsDomains. Начинайте домены и поддомены с точки ( .).

withMonitoredDomainsметод

Java:

new AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredDomains("<domain1>", "<domain2>")
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredDomains("<domain1>", "<domain2>")
    .buildConfiguration()

withMonitoredHttpsDomainsметод

ЕдиныйАгент для Android версии 8.237+

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

Java:

new AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredHttpsDomains("https://<domain1>", "https://<domain2>")
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredHttpsDomains("https://<domain1>", "https://<domain2>")
    .buildConfiguration()

ИнструментWebView

Чтобы обеспечить обмен данными между RUM JavaScript и ЕдиныйАгент для Android, WebViewперед загрузкой URL-адреса все объекты необходимо обработать с помощью WebView.loadUrl(String). Инструментируйте Astromkey.instrumentWebViewметод для каждого WebView, который содержит RUM JavaScript. Без этого данные мониторинга не могут быть связаны с одним и тем же сеансом.

Java:

WebView myWebView = (WebView) findViewById(R.id.webview);
Astromkey.instrumentWebView(myWebView);
myWebView.loadUrl("http://www.example.com");

Kotlin:

val myWebView: WebView = findViewById(R.id.webview)
Astromkey.instrumentWebView(myWebView)
myWebView.loadUrl("http://www.example.com")

Из соображений безопасности этот вызов API игнорируется на устройствах с версиями API 15 и 16.

Сохраняйте файлы cookie Ключ-АСТРОМ

Для гибридных приложений важно убедиться, что файлы cookie Ключ-АСТРОМ не удалены. Без этих файлов cookie Ключ-АСТРОМ не может объединить данные мониторинга из RUM JavaScript и ЕдиныйАгент для Android в один сеанс.

Когда вы удаляете файлы cookie с помощью CookieManager#removeAllCookies(ValueCallback)или CookieManager#removeSessionCookies(ValueCallback), вы также должны вызвать restoreCookiesметод для восстановления файлов cookie Ключ-АСТРОМ.

Java:

CookieManager.getInstance().removeAllCookies(null);
Astromkey.restoreCookies();

Kotlin:

CookieManager.getInstance().removeAllCookies(null)
Astromkey.restoreCookies()

Включить балансировку нагрузки

ЕдиныйАгент позволяет включить балансировку нагрузки на стороне клиента, что помогает избежать несбалансированной нагрузки на сервер, когда несколько ЕдиныыхАгентов одновременно устанавливают соединение с АктивномШлюзе.

Java:

new AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withStartupLoadBalancing(true)
    .buildConfiguration();

Kotlin:

AstromkeyConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withStartupLoadBalancing(true)
    .buildConfiguration()