Просмотр кода страницы Инструментирование мобильных приложений с помощью пакета Ключ-АСТРОМ 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''' во все необходимые проекты.

# В '''Visual Studio''' щелкните правой кнопкой мыши по основному проекту приложения и выберите '''Управление пакетами NuGet'''.
# Найдите пакет '''astromkey.OneAgent.Xamarin''' на [https://nuget.org nuget.org] и выберите '''Добавить пакет'''.
# Установите флажки для всех проектов, в которые хотите добавить пакет.
# Выберите '''ОК'''.

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

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

=== Шаг 3: Добавление файла конфигурации в проект ===
Добавьте скачанный файл <code>astromkey.config.json</code> в свой проект.

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

=== Шаг 4: Добавление метода запуска ЕдиногоАгента ===
Для запуска ЕдиногоАгента используйте следующий код (общий для обеих платформ).
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

Agent.Instance.Start();
</pre>
|}

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

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

Пример для '''Android Forms''':
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

Xamarin.Essentials.Platform.Init(this, savedInstanceState);
global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
Xamarin.Forms.DependencyService.RegisterSingleton&lt;Iastromkey&gt;(Agent.Instance);
LoadApplication(new App());
</pre>
|}
Доступ к ЕдиногоАгенту в приложении '''Xamarin.Forms''':
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

Iastromkey astromkey= DependencyService.Get&lt;Iastromkey&gt;();
</pre>
|}
При автоматической инструментации необходимо также применить пакет к нативным частям приложения.

Для версий '''Xamarin.Forms 4.6.0''' и более ранних используйте обходное решение. В файле <code>App.xaml.cs</code>:
{| class="wikitable"
|<pre>
public partial class App : Application
{
    static readonly Dictionary&lt;Type, Func&lt;object, object&gt;&gt; factories = new Dictionary&lt;Type, Func&lt;object, object&gt;&gt;();

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

    public static void Register(Type type, Func&lt;object, object&gt; factory)
    {
        factories[type] = factory;
    }
    ...
}
</pre>
|}
В части для '''Android''':
{| class="wikitable"
|<pre>
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());
    }
    ...
}
</pre>
|}

=== Шаг 6 (необязательно): Включение автоматической инструментации веб-запросов ===
Для автоматической инструментации веб-запросов используйте следующий метод. <code>HttpMessageHandler</code>, используемый в <code>HttpClient</code>, отвечает за ручную инструментацию веб-запросов.
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

var httpHandler = Agent.Instance.GetHttpMessageHandler();
var httpClient = new HttpClient(httpHandler);
</pre>
|}
С собственным обработчиком:
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

var defaultHttpHandler = new HttpClientHandler();
var httpHandler = Agent.Instance.GetHttpMessageHandler(defaultHttpHandler);
var httpClient = new HttpClient(httpHandler);
</pre>
|}

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

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

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

* '''Android''':

{| class="wikitable"
|<pre>
{
    "android": {
        "autoStart": {
            "enabled": false
        }
    }
}
</pre>
|}

* '''iOS''':

{| class="wikitable"
|<pre>
{
  "ios": {
    "DTXAutoStart": false
  }
}
</pre>
|}
Не добавляйте дополнительные свойства в файл конфигурации, иначе сборка завершится с ошибкой.

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

* '''Android''':

{| class="wikitable"
|<pre>
using astromkey.Xamarin;

Agent.Instance.Start(new ConfigurationBuilder("&lt;insertBeaconURL&gt;", "&lt;insertApplicationID&gt;").BuildConfiguration());
</pre>
|}

* '''iOS''':

{| class="wikitable"
|<pre>
using astromkey.Xamarin;

var configDict = new Dictionary&lt;string, object&gt;();
configDict.Add("DTXApplicationID", "&lt;insertApplicationID&gt;");
configDict.Add("DTXBeaconURL", "&lt;insertBeaconURL&gt;");
Agent.Instance.Start(configDict);
</pre>
|}

=== Создание пользовательских действий ===
Вызов <code>EnterAction</code> для запуска и <code>LeaveAction</code> для завершения пользовательского действия. Время выполнения измеряется автоматически.
{| class="wikitable"
|<pre>
using astromkey.Xamarin;

var myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
// Выполнить действие
myAction.LeaveAction();
</pre>
|}
Максимальная длина имени пользовательского действия — 250 символов.

=== Создание дочерних действий ===
Дочерние действия аналогичны родительским. При закрытии родительского все дочерние закрываются автоматически.
{| class="wikitable"
|<pre>
var myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
var mySubAction = myAction.EnterAction("Нажмите на подтверждение еще раз");
mySubAction.LeaveAction();
myAction.LeaveAction();
</pre>
|}
Максимальная длина имени — 250 символов. Можно создать только один уровень дочерних действий.

=== Отмена пользовательских действий ===
Вызов <code>Cancel</code> отменяет действие и все связанные с ним данные (значения, события, ошибки, дочерние действия).
{| class="wikitable"
|<pre>
var myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
myAction.Cancel(); // Действие отменено
</pre>
|}
Нельзя отменить закрытое действие и закрыть отменённое.

=== Инструментация веб-запросов ===
{| class="wikitable"
|<pre>
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();
}
</pre>
|}

=== Сообщение значения ===
Метод <code>ReportValue</code> позволяет передавать пары «ключ-значение» типов <code>int</code>, <code>double</code>, <code>string</code>.
{| class="wikitable"
|<pre>
var myAction = Agent.Instance.EnterAction("Нажмите на подтверждение");
myAction.ReportValue("Тип клиента", "Золото");
myAction.LeaveAction();
</pre>
|}
Значения можно просмотреть на странице подробной информации о действии пользователя в разделе «Отображаемые значения».

=== Сообщение о событии ===
{| class="wikitable"
|<pre>
myAction.ReportEvent(eventName);
</pre>
|}

=== Сообщение об ошибке ===
{| class="wikitable"
|<pre>
myAction.ReportError(errorName, errorCode);
</pre>
|}

=== Сообщение о трассировке стека ошибок ===
{| class="wikitable"
|<pre>
Agent.Instance.ReportErrorStacktrace("Error_Class", "Error_Value", "Error_Reason", "Error_Stacktrace");
</pre>
|}

=== Сообщение о сбое ===
{| class="wikitable"
|<pre>
Agent.Instance.ReportCrash("CrashWithoutException", "Crash_Reason", "Crash_Stacktrace");
// или с объектом исключения
Agent.Instance.ReportCrashWithException("CrashWithExceptionObj", exception);
</pre>
|}

* '''Android''': информация о сбое отправляется сразу после возникновения; иногда требуется повторное открытие приложения в течение 10 минут.
* '''iOS''': информация отправляется при следующем запуске приложения; если пользователь не открывает приложение в течение 10 минут, отчет удаляется.

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

=== Сообщение о деловом событии ===
Функция доступна с версии Ключ-АСТРОМ SaaS 1.253+.
{| class="wikitable"
|<pre>
var attributes = new Dictionary&lt;string, JsonValue&gt;();
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);
</pre>
|}

=== Отметка конкретных пользователей ===
Присвоение уникального имени пользовательской сессии.
{| class="wikitable"
|<pre>
Agent.Instance.IdentifyUser("John Smith");
</pre>
|}
При автоматическом перезапуске сессии (по тайм-ауту или неактивности) метка сохраняется.

=== Завершение сессии ===
Принудительное завершение сессии и запуск новой.
{| class="wikitable"
|<pre>
Agent.Instance.EndVisit();
</pre>
|}

=== Настройка конфиденциальности данных (режим согласия) ===
Включение режима согласия пользователя: установите <code>userOptIn: true</code> ('''Android''') или <code>DTXUserOptIn: true</code> ('''iOS''') в файле конфигурации.

Получение текущих настроек:
{| class="wikitable"
|<pre>
UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();
bool crashOptedIn = currentOptions.CrashReportingOptedIn;
DataCollectionLevel dataCollectionLevel = currentOptions.DataCollectionLevel;
</pre>
|}
Изменение настроек:
{| class="wikitable"
|<pre>
UserPrivacyOptions options = new UserPrivacyOptions(DataCollectionLevel.Performance, false);
options.DataCollectionLevel = DataCollectionLevel.UserBehavior;
options.CrashReportingOptedIn = true;
Agent.Instance.ApplyUserPrivacyOptions(options);
</pre>
|}
Возможные уровни: <code>Off</code>, <code>Performance</code>, <code>UserBehavior</code>.

=== Сообщение местоположения по GPS ===
{| class="wikitable"
|<pre>
Agent.Instance.SetGPSLocation(latitude, longitude);
</pre>
|}

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

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

Пример структуры для '''Android''':
{| class="wikitable"
|<pre>
{
    "android": {
        "autoStart": {
            "applicationId": "&lt;insertApplicationID&gt;",
            "beaconUrl": "&lt;insertBeaconURL&gt;"
        },
        "userOptIn": true,
        "agentBehavior": {
            "startupLoadBalancing": true
        }
    }
}
</pre>
|}
Пример структуры для '''iOS''':
{| class="wikitable"
|<pre>
{
  "ios": {
    "DTXApplicationId": "&lt;insertApplicationID&gt;",
    "DTXBeaconUrl": "&lt;insertBeaconURL&gt;",
    "DTXUserOptIn": true,
    "DTXStartupLoadBalancing": true
  }
}
</pre>
|}
Никогда не используйте точечную нотацию для конфигурационного файла. Всегда пишите в квадратных скобках.

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

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

* '''Android''':

{| class="wikitable"
|<pre>
{
    "android": {
        "autoStart": { ... },
        "userOptIn": true,
        "debug": {
            "agentLogging": true
        }
    }
}
</pre>
|}

* '''iOS''':

{| class="wikitable"
|<pre>
{
  "ios": {
    "DTXApplicationId": "&lt;insertApplicationID&gt;",
    "DTXBeaconUrl": "&lt;insertBeaconURL&gt;",
    "DTXUserOptIn": true,
    "DTXLogLevel": "ALL"
  }
}
</pre>
|}

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

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