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

Материал из Документация Ключ-АСТРОМ
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

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

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

Прекращение поддержки и устаревание пакета

С 1 мая 2024 года Microsoft прекратила поддержку всех SDK Xamarin. По этой причине поддержка пакета Ключ-АСТРОМ Xamarin NuGet также прекращена в мае 2024 года. В последующих версиях пакета будут только исправления ошибок и важные проблемы безопасности.

Кроме того, в соответствии с политикой поддержки Ключ-АСТРОМ, поддержка пакета полностью прекращена в мае 2025 года.

Рекомендуется обновить проекты Xamarin до .NET и использовать пакет Ключ-АСТРОМ .NET MAUI NuGet вместо устаревшего пакета Xamarin NuGet.

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

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

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

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

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

Требования

  • Для Android:
    • Android версии 5.0+ (API 21+)
    • Xamarin.Android SDK 10.1.x+
  • Для iOS: версия iOS 12+
  • Для Xamarin.Forms: .NET Standard версии 2.0 и выше

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

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

Добавьте пакет Ключ-АСТРОМ Xamarin NuGet во все необходимые проекты.

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

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

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

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

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

Добавьте скачанный файл astromkey.config.json в свой проект.

  • Android: добавьте файл в каталог Assets вашего Android-проекта.
  • iOS: добавьте файл в каталог Resources вашего iOS-проекта. Перед каждой сборкой пакет автоматически создает новый файл astromkey.plist на основе параметров из конфигурационного файла.

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

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

using astromkey.Xamarin;

Agent.Instance.Start();

Шаг 5: Настройка DependencyService для Xamarin.Forms

Только для Xamarin.Forms

Для версий Xamarin.Forms 4.7.0 и выше, использующих RegisterSingleton, зарегистрируйте интерфейс при запуске в нативной части приложения Xamarin.Forms сразу после Forms.Init().

Пример для Android Forms: 

using astromkey.Xamarin;

Xamarin.Essentials.Platform.Init(this, savedInstanceState);
global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
Xamarin.Forms.DependencyService.RegisterSingleton<Iastromkey>(Agent.Instance);
LoadApplication(new App());

Доступ к ЕдиногоАгенту в приложении Xamarin.Forms: 

using astromkey.Xamarin;

Iastromkey astromkey= DependencyService.Get<Iastromkey>();

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

Для версий Xamarin.Forms 4.6.0 и более ранних используйте обходное решение. В файле App.xaml.cs: 

public partial class App : Application
{
    static readonly Dictionary<Type, Func<object, object>> factories = new Dictionary<Type, Func<object, object>>();

    public App()
    {
        InitializeComponent();
        DependencyResolver.ResolveUsing((type, args) => factories.ContainsKey(type) ? factories[type].Invoke(args) : null);
        Iastromkey astromkey = DependencyService.Resolve<Iastromkey>();
        astromkey.Start(null);
    }

    public static void Register(Type type, Func<object, object> factory)
    {
        factories[type] = factory;
    }
    ...
}

В части для Android: 

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
{
    protected override void OnCreate(Bundle savedInstanceState)
    {
        ...
        Xamarin.Essentials.Platform.Init(this, savedInstanceState);
        global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
        App.Register(typeof(Iastromkey), (o) => Agent.Instance);
        LoadApplication(new App());
    }
    ...
}

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

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

using astromkey.Xamarin;

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

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

using astromkey.Xamarin;

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.Xamarin;

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

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

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

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

using astromkey.Xamarin;

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

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

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

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

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

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

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

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

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

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

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

var webAction = Agent.Instance.EnterAction(actionName: "WebRequest Action");
string requestTag = webAction.GetRequestTag(url);
string requestTagHeader = webAction.GetRequestTagHeader();
httpClient.DefaultRequestHeaders.Add(requestTagHeader, requestTag);
WebRequestTiming timing = (WebRequestTiming)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. 

var 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 минут, отчет удаляется.

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

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

Функция доступна с версии Ключ-АСТРОМ SaaS 1.253+. 

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

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

Файл astromkey.config.json содержит идентификатор приложения, URL-адрес маяка и другие настройки. Можно скачать из Ключ-АСТРОМ или создать вручную. Если файл отсутствует, сборка завершится ошибкой (если не используется ручной запуск).

При использовании конфигураций сборки (Debug, Release) пакет ищет файл с именем astromkey<Configuration>.config.json. Можно указать собственный путь через свойство astromkeyConfigurationFile.

Пример структуры для 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": { ... },
        "userOptIn": true,
        "debug": {
            "agentLogging": true
        }
    }
}
  • iOS:
{
  "ios": {
    "DTXApplicationId": "<insertApplicationID>",
    "DTXBeaconUrl": "<insertBeaconURL>",
    "DTXUserOptIn": true,
    "DTXLogLevel": "ALL"
  }
}

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

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

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

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

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