Инструментирование мобильных приложений с помощью пакета NuGet Ключ-АСТРОМ .NET MAUI

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

Инструментирование мобильных приложений с помощью пакета NuGet Ключ-АСТРОМ .NET MAUI в RUM Classic

Пакет NuGet Ключ-АСТРОМ .NET MAUI помогает автоматически инструментировать ваше мобильное приложение .NET MAUI с помощью ЕдиногоАгента для Android и iOS, а также предоставляет API для ручной инструментации.

Пакет Ключ-АСТРОМ .NET MAUI NuGet доступен для Android и iOS. Наш пакет недоступен для macOS и Windows.

Поддерживаемые функции

Автоматическая инструментация

  • Действия пользователя
  • События жизненного цикла
  • Веб-запросы
  • Аварии

Ручная инструментация

  • Пользовательские действия
  • Веб-запросы
  • Ценности
  • События
  • Ошибки
  • Аварии
  • Теги пользователей

Требования

  • Для Android: версия Android 6.0+ (API 23+)
  • Для iOS: версия iOS 15+

Настройка пакета

Шаг 1: Установка пакета NuGet

Добавьте пакет NuGet Ключ-АСТРОМ .NET MAUI в ваше приложение.

  1. В Visual Studio щелкните правой кнопкой мыши по решению вашего мобильного приложения и выберите Управление пакетами NuGet.
  2. Найдите пакет Astromkey.OneAgent.MAUI на nuget.org и выберите Добавить пакет.
  3. Установите флажки для всех проектов, в которые вы хотите добавить пакет NuGet. Убедитесь, что вы добавляете пакет в свои собственные проекты, поскольку целевые файлы внутри нашего пакета взаимодействуют со сборкой.
  4. Выберите ОК.

Шаг 2: Создание приложения и получение файла конфигурации

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

  1. В Ключ-АСТРОМ перейдите в раздел Мобильное приложение.
  2. Выберите Создать мобильное приложение.
  3. Введите название для вашего приложения и выберите Создать мобильное приложение. Откроется страница настроек приложения.
  4. В настройках приложения выберите Мастер инструментирования > .NET MAUI.
  5. На шаге 2 выберите Загрузить astromkey.config.json, чтобы получить файл конфигурации.

Шаг 3: Добавление файла конфигурации в проект

Добавьте файл astromkey.config.json, который вы скачали на предыдущем шаге, в свой проект. Вы можете сделать это любым из следующих способов, но мы перечислили их в порядке от наиболее рекомендуемого к наименее рекомендуемому.

  • Добавьте файл astromkey.config.json в указанное вами местоположение. Укажите это местоположение с помощью свойства AstromkeyConfigurationFile.
  • Добавьте файл astromkey.config.json в:
    • Директорию Platforms/Android/Assets вашего проекта (Android). Если директория Assets не существует, создайте её внутри существующей директории Platforms/Android.
    • Директорию Platforms/iOS/Resources вашего проекта (iOS). Если директория Resources не существует, создайте её внутри существующей директории Platforms/iOS.
  • Добавьте файл astromkey.config.json в корневой каталог вашего проекта. MSBuild автоматически устанавливает корневой каталог с помощью соответствующего свойства ProjectDir.

При миграции вашего проекта Xamarin в проект .NET и переходе на пакет NuGet Ключ-АСТРОМ .NET MAUI добавьте файл astromkey.config.json в указанное вами местоположение или в корневой каталог вашего проекта.

Шаг 4: Добавление метода запуска ЕдиногоАгента

Для запуска ЕдиногоАгента используйте следующий код (общий для обеих платформ). 

using Astromkey.MAUI;

Agent.Instance.Start();

Шаг 5 (необязательно): Включение автоматической инструментации веб-запросов

Для автоматической инструментации веб-запросов используйте следующий метод. HttpMessageHandler, используемый в HttpClient, отвечает за ручную инструментацию веб-запросов. 

using Astromkey.MAUI;

var httpHandler = Agent.Instance.GetHttpMessageHandler();
var httpClient = new HttpClient(httpHandler);

С собственным обработчиком: 

using Astromkey.MAUI;

var defaultHttpHandler = new HttpClientHandler();
var httpHandler = Agent.Instance.GetHttpMessageHandler(defaultHttpHandler);
var httpClient = new HttpClient(httpHandler);

Ручная инструментация

Запуск ЕдиногоАгента

Можно использовать ручной запуск с помощью конструктора конфигураций (Android) или словаря конфигураций (iOS).

Измените файл astromkey.config.json, чтобы отключить автозапуск:

  • Android:
{
    "android": {
        "autoStart": {
            "enabled": false
        }
    }
}
  • iOS:
{
  "ios": {
    "DTXAutoStart": false
  }
}

Не добавляйте дополнительные свойства в файл конфигурации, иначе сборка завершится с ошибкой.

Запустите ЕдиныйАгент вручную:

  • Android:
using Astromkey.MAUI;

Agent.Instance.Start(new ConfigurationBuilder("<insertBeaconURL>", "<insertApplicationID>").BuildConfiguration());
  • iOS:
using Astromkey.MAUI;

var configDict = new Dictionary<string, object>();
configDict.Add("DTXApplicationID", "<insertApplicationID>");
configDict.Add("DTXBeaconURL", "<insertBeaconURL>");
Agent.Instance.Start(configDict);

Создание пользовательских действий

Вызов EnterAction для запуска и LeaveAction для завершения пользовательского действия. Время выполнения измеряется автоматически. 

using Astromkey.MAUI;

IRootAction myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
// Выполнить действие
myAction.LeaveAction();

Максимальная длина имени пользовательского действия — 250 символов.

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

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

IRootAction myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
IAction mySubAction = myAction.EnterAction("Нажмите на подтверждение еще раз");
mySubAction.LeaveAction();
myAction.LeaveAction();

Максимальная длина имени — 250 символов. Можно создать только один уровень дочерних действий.

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

Вызов Cancel отменяет действие и все связанные с ним данные (значения, события, ошибки, дочерние действия). 

IRootAction myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
myAction.Cancel(); // Действие отменено

Нельзя отменить закрытое действие и закрыть отменённое.

Инструментация веб-запросов

IRootAction webAction = Agent.Instance.EnterAction(actionName: "WebRequest Action");
string requestTag = webAction.GetRequestTag(url);
string requestTagHeader = webAction.GetRequestTagHeader();
httpClient.DefaultRequestHeaders.Add(requestTagHeader, requestTag);
IWebRequestTiming timing = Agent.Instance.GetWebRequestTiming(requestTag, url);
timing.StartWebRequestTiming();
try
{
    var response = await httpClient.GetAsync(url);
    timing.StopWebRequestTiming(url, (int)response.StatusCode, response.ReasonPhrase);
}
catch (HttpRequestException)
{
    timing.StopWebRequestTiming(url, -1, Exception.ToString());
}
finally
{
    webAction.LeaveAction();
}

Сообщение значения

Метод ReportValue позволяет передавать пары «ключ-значение» типов int, double, string. 

IRootAction myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
myAction.ReportValue("Тип клиента", "Золото");
myAction.LeaveAction();

Сообщение о событии

myAction.ReportEvent(eventName);

Сообщение об ошибке

myAction.ReportError(errorName, errorCode);

Сообщение о трассировке стека ошибок

Agent.Instance.ReportErrorStacktrace("Error_Class", "Error_Value", "Error_Reason", "Error_Stacktrace");

Сообщение о сбое

Agent.Instance.ReportCrash("CrashWithoutException", "Crash_Reason", "Crash_Stacktrace");
// или с объектом исключения
Agent.Instance.ReportCrashWithException("CrashWithExceptionObj", exception);
  • Android: информация о сбое отправляется сразу после возникновения; иногда требуется повторное открытие приложения в течение 10 минут.
  • iOS: информация отправляется при следующем запуске приложения; если пользователь не открывает приложение в течение 10 минут, отчет удаляется.

Сообщение о сбое завершает текущую пользовательскую сессию.

Сообщение о деловом событии

var attributes = new Dictionary<string, JsonValue>();
attributes.Add("event.name", "Confirmed Booking");
attributes.Add("screen", "booking-confirmation");
attributes.Add("product", "Danube Anna Hotel");
attributes.Add("amount", 358.35);
attributes.Add("currency", "USD");
attributes.Add("reviewScore", 4.8);
attributes.Add("arrivalDate", "2022-11-05");
attributes.Add("departureDate", "2022-11-15");
attributes.Add("journeyDuration", 10);
attributes.Add("adultTravelers", 2);
attributes.Add("childrenTravelers", 0);

Agent.Instance.SendBizEvent("com.easytravel.funnel.booking-finished", attributes);

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

Присвоение уникального имени пользовательской сессии. 

Agent.Instance.IdentifyUser("John Smith");

При автоматическом перезапуске сессии (по тайм-ауту или неактивности) метка сохраняется.

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

Принудительное завершение сессии и запуск новой. 

Agent.Instance.EndVisit();

Настройка конфиденциальности данных (режим согласия)

Включение режима согласия пользователя: установите userOptIn: true (Android) или DTXUserOptIn: true (iOS) в файле конфигурации.

Получение текущих настроек: 

UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();
bool crashOptedIn = currentOptions.CrashReportingOptedIn;
DataCollectionLevel dataCollectionLevel = currentOptions.DataCollectionLevel;

Изменение настроек: 

UserPrivacyOptions options = new UserPrivacyOptions(DataCollectionLevel.Performance, false);
options.DataCollectionLevel = DataCollectionLevel.UserBehavior;
options.CrashReportingOptedIn = true;
Agent.Instance.ApplyUserPrivacyOptions(options);

Возможные уровни: Off, Performance, UserBehavior.

Сообщение местоположения по GPS

Agent.Instance.SetGPSLocation(latitude, longitude);

Потолочное оборудование

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

Операционная система Шаблон приложения Версия Размер до Размер после Разница
Android Новое приложение по умолчанию net8.0-android 31,8 МБ 32,4 МБ 0,6 МБ
iOS Новое приложение по умолчанию net8.0-ios 421 МБ 426,2 МБ 5,2 МБ

Файл конфигурации

В файле astromkey.config.json содержится идентификатор вашего приложения, URL-адрес маяка и некоторые другие настройки.

Этот файл можно скачать с сайта Ключ-АСТРОМ или создать вручную.

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

При использовании определенной конфигурации сборки — например, Debug, Release, или пользовательской конфигурации — наш пакет ищет в каталоге Assets (Android) или Resources (iOS) файл конфигурации с именем astromkey<Configuration>.config.json. Например, если вы используете Debug конфигурацию сборки, наш пакет ищет файл с именем astromkeyDebug.config.json.

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

Создайте Directory.Build.props в каталоге проекта Android/iOS (или общем каталоге): 

<Project>
  <PropertyGroup>
    <AstromkeyConfigurationFile>CUSTOM_PATH/astromkey.config.json</AstromkeyConfigurationFile>
  </PropertyGroup>
</Project>

В итоге, это приводит к следующему порядку использования конфигурации:

  1. Путь к пользовательской конфигурации через свойство AstromkeyConfigurationFile
  2. Файл, специфичный для конфигурации, например: astromkey<Configuration>.config.json
  3. Имя по умолчанию astromkey.config.json

Пример структуры для Android: 

{
    "android": {
        "autoStart": {
            "applicationId": "<insertApplicationID>",
            "beaconUrl": "<insertBeaconURL>"
        },
        "userOptIn": true,
        "agentBehavior": {
            "startupLoadBalancing": true
        }
    }
}

Пример структуры для iOS: 

{
  "ios": {
    "DTXApplicationId": "<insertApplicationID>",
    "DTXBeaconUrl": "<insertBeaconURL>",
    "DTXUserOptIn": true,
    "DTXStartupLoadBalancing": true
  }
}

Никогда не используйте точечную нотацию для конфигурационного файла. Всегда пишите в квадратных скобках.

Включение отладочных логов

Логи ЕдиногоАгента

  • Android:
{
    "android": {
        "autoStart": {
            "applicationId": "<insertApplicationID>",
            "beaconUrl": "<insertBeaconURL>"
        },
        "userOptIn": true,
        "debug": {
            "agentLogging": true
        }
    }
}
  • iOS:
{
  "ios": {
    "DTXApplicationId": "<insertApplicationID>",
    "DTXBeaconUrl": "<insertBeaconURL>",
    "DTXUserOptIn": true,
    "DTXLogLevel": "ALL"
  }
}

Отладочные логи сборки (только Android)

Установите свойство AstromkeyInstrumentationLogging в true (через Directory.Build.props или .csproj), измените уровень детализации вывода сборки на Diagnostic.

Поиск неисправностей

См. раздел «Мобильные приложения: проблемы с пакетом NuGet Ключ-АСТРОМ .NET MAUI» в сообществе Ключ-АСТРОМ.

Источник — https://doc.ruscomtech.ru/index.php?title=Инструментирование_мобильных_приложений_с_помощью_пакета_NuGet_Ключ-АСТРОМ_.NET_MAUI&oldid=6497