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

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

Вы можете использовать OneAgent SDK в Java и Kotlin.

Запустить OneAgent

Если вы отключили автоматический запуск с помощью autoStart.enabledсвойства или используете автономное ручное инструментирование вместо автоматического, запустите OneAgent вручную в 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())
    }
}

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

Java:

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

Kotlin:

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

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

OneAgent для Android версии 8.229 и более ранних версий

Если вы отключили автоматический запуск с помощью autoStart.enabledсвойства или используете автономное ручное инструментирование вместо автоматического, запустите OneAgent вручную в 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оно никогда не вызывается из компонента, поддерживающего прямую загрузку. Также см. раздел Настройка связи с OneAgent SDK для Android , чтобы убедиться, что OneAgent может передавать данные в кластер Ключ-АСТРОМ.

Настроить OneAgent

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

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. OneAgent не добавляет автоматически дополнительные события, такие как веб-запросы, в настраиваемые действия или закрытие настраиваемых действий. Однако, когда OneAgent завершает работу или должен начать новый сеанс, он закрывает все открытые дополнительные действия.

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

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

Вызов 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 минут и не закрывается, такое действие отбрасывается и не сообщается Ключ-АСТРОМ.

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

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

Создайте дочерние действия с помощью 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 символов.

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

OneAgent для 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()
}

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

OneAgent для Android версии 8.231+

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

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

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

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

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

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

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

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()
    }
}

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

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

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

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

Java:

action.reportEvent("event_name");

Kotlin:

action.reportEvent("event_name")

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

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

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

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

• int
• long
• double
• string

Метрики с типом longподдерживаются для OneAgent 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метода, поскольку он конкретно идентифицируется как событие типа ошибки.

OneAgent 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)

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

OneAgent для Android версии 8.253+

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

Дополнительные сведения о бизнес-событиях см. в разделе Бизнес-аналитика в 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
}

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

OneAgent для Android версии 8.223+

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

• Отображение активности : измеряет временной интервал от 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-ответ и тело ответа.
   • Возникает исключение соединения.

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

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

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

Чтобы прикрепить веб-запрос к действию пользователя, сгенерируйте уникальный тег с помощью 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)

OneAgent для Android версии 8.249+

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

OneAgent для 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()
    }
})

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

OneAgent фиксирует все необработанные исключения и ошибки и немедленно отправляет отчет о сбое на сервер. Отчет о сбое 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")

OneAgent для Android версии 237+

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

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

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

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

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

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

Вы можете принудительно завершить сеанс с помощью Ключ-АСТРОМ 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()
)

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

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

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

OneAgent для Android версии 8.189 и более ранних версий

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

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

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

Для гибридных приложений, использующих RUM JavaScript внутри WebView(Android) или WKWebView(iOS), файлы cookie должны быть установлены для каждого инструментированного домена или сервера, с которым взаимодействует приложение. Когда функция мониторинга гибридных приложений включена, OneAgent создает эти файлы 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метод

OneAgent для 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 и OneAgent для 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 и OneAgent для Android в один сеанс.

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

Java:

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

Kotlin:

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

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

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

Java:

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

Kotlin:

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