Instrument mobile apps with Dynatrace Xamarin NuGet package

The Dynatrace Xamarin NuGet package helps auto-instrument your Xamarin app with OneAgent for Android and iOS as well as provides an API for manual instrumentation. The package is compatible with Xamarin.iOS, Xamarin.Android, and Xamarin.Forms projects.

Supported features

Requirements

Set up the package

Perform the following steps to set up the Dynatrace Xamarin NuGet package for your Xamarin app.

Install the Dynatrace Xamarin NuGet package

Create an application and get the config file

Add the config file to your project

Add the OneAgent start method

Xamarin.Forms only

Set up Xamarin.Forms DependencyService

Enable automatic web request instrumentation

Install the NuGet package

Add the Dynatrace Xamarin NuGet package to all the required projects.

Create an application and get the config file

Create a new mobile application in Dynatrace and download the configuration file.

Add the config file to your project

Add the dynatrace.config.json file, which you downloaded in the previous step, to your project.

Add the OneAgent start method

The start method is required for OneAgent to start.

using Dynatrace.Xamarin;

Agent.Instance.Start();

using Dynatrace.Xamarin;

Agent.Instance.Start();

Set up Xamarin.Forms DependencyService

Xamarin.Forms only

This instruction is for Xamarin.Forms versions 4.7.0+, which use RegisterSingleton. For earlier Xamarin.Forms versions, see the instruction below.

Register the interface at startup in the native part of your Xamarin.Forms application, and paste the following code right after Forms.Init().

The following example is for an Android Forms application:

using Dynatrace.Xamarin;

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

LoadApplication(new App());

The following code in your Xamarin.Forms application allows you to access OneAgent:

using Dynatrace.Xamarin;

IDynatrace dynatrace = DependencyService.Get<IDynatrace>();

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

        IDynatrace Dynatrace = DependencyService.Resolve<IDynatrace>();
        Dynatrace.Start(null);
    }

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

    ...
}

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(IDynatrace), (o) => Agent.Instance);

        LoadApplication(new App());
    }

    ...
}

Enable automatic web request instrumentation optional

You can optionally use the following method to enable the auto-instrumentation of web requests. The HttpMessageHandler used by HttpClient takes care of the manual web request instrumentation.

using Dynatrace.Xamarin;

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

Moreover, you can also have your own HTTP handler:

using Dynatrace.Xamarin;

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

Manual instrumentation

The sections below describe how to start OneAgent manually, create custom actions, instrument web requests, and report values, events, and crashes.

Start OneAgent

You can use the manual startup with a configuration builder (Android) or a configuration dictionary (iOS).

Create custom actions

You can create custom actions and enhance them with additional information such as values, events, and errors.

Call EnterAction to start a custom action and LeaveAction to close a custom action. Timing is measured automatically.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("Tap on Confirm");
//Perform the action and whatever else is needed.
myAction.LeaveAction();

Create child actions

Besides generating standalone custom actions, you can also create child actions.

Child actions are similar to parent custom actions. When a parent action is closed, all child actions of the parent action are automatically closed.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("Tap on Confirm");
var mySubAction = myAction.EnterAction("Tap on Confirm again");
//Perform the action and whatever else is needed.
mySubAction.LeaveAction();
myAction.LeaveAction();

There's no limit on the number of child actions attached to a custom action. However, note that you can have only one level of child actions—you can't create a child action for another child action (child actions can't have their own child actions). Also, refer to User session structure for individual user.

Child actions are not displayed on the user session details page, but you can view them on the waterfall analysis page for a custom action to which these child actions are attached.

Cancel custom actions

If you need to cancel an already created but not yet closed custom action, call Cancel. Canceling an action discards all data associated with it: all reported values, events, and errors are discarded; all child actions are canceled.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("Tap on Confirm");
// Action is canceled
myAction.Cancel();

Instrument web requests

Use the following code snippet to instrument web requests:

using Dynatrace.Xamarin;

// Create an action
var webAction = Agent.Instance.EnterAction(actionName: "WebRequest Action");
// Generate a new unique tag associated with the web request action
string requestTag = webAction.GetRequestTag(url);
string requestTagHeader = webAction.GetRequestTagHeader();
// Place the Dynatrace HTTP header on your web request
httpClient.DefaultRequestHeaders.Add(requestTagHeader, requestTag);
// Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = (WebRequestTiming)Agent.Instance.GetWebRequestTiming(requestTag, url);
// Start web request timing before the HTTP request is sent
timing.StartWebRequestTiming();
try
{
  var response = await httpClient.GetAsync(url);
  // Stop web request timing when the HTTP response is received and the response body is obtained
  timing.StopWebRequestTiming(url, (int)response.StatusCode, response.ReasonPhrase);
}
catch (HttpRequestException exception)
{
  // Stop web request timing when a connection exception occurs
  timing.StopWebRequestTiming(url, -1, exception.ToString());
}
finally
{
  // Leave an action
  webAction.LeaveAction();
}

Report a value

The reportValue method allows you to report key-value pairs of metadata that you can later view in the Dynatrace web UI and convert into user action and user session properties. The reported values must be part of a user action.

You can report values of the following data types:

ReportValue(valueName: string, value: int);
ReportValue(valueName: string, value: double);
ReportValue(valueName: string, value: string);

For instance, to report a string value within the Tap on Confirm action, use the following code:

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("Tap on Confirm");
myAction.ReportValue("Customer type", "Gold");
myAction.LeaveAction();

To view the reported values in the Dynatrace web UI, go to the details of the user action that should contain that metadata and scroll down to the Reported values section.

To add action and session properties based on the reported values and then use these properties to create powerful queries, segmentations, and aggregations, see Define user action and user session properties for mobile applications.

Report an event

For any open action, you can report an event. Use the following API call:

ReportEvent(eventName: string);

Report an error

To report an error, use the ReportError method.

ReportError(errorName: string, errorCode: number);

Report an error stack trace

To report an error stack trace, use the following API call:

using Dynatrace.Xamarin;

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

Report a crash

To report a crash, use the following API call.

using Dynatrace.Xamarin;

Agent.Instance.ReportCrash("CrashWithoutException", "Crash_Reason", "Crash_Stacktrace");

You can also use an exception object:

using Dynatrace.Xamarin;

Agent.Instance.ReportCrashWithException("CrashWithExceptionObj", exception);

The time when the crash details are sent to Dynatrace depends on your mobile application operating system.

Report a business event

Dynatrace SaaS version 1.253+

With sendBizEvent, you can report business events. These are standalone events, as Dynatrace sends them separately from user actions or user sessions.

Business events are only captured for monitored sessions. When OneAgent is disabled either through a special flag or due to cost and traffic control, business events are not reported for such sessions. Note that this behavior might be subject to change in the future, potentially allowing business events to be sent to Dynatrace regardless of session monitoring.

For additional details on business events, refer to Business Analytics.

using Dynatrace.Xamarin;

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

Tag specific users

You can tag each user of your application with a unique user name. This enables you to search and filter specific user sessions and analyze individual user behavior over time. For more details, see User tagging.

Make the following API call to tag the current session with a particular name:

using Dynatrace.Xamarin;

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

End a session

You can force a session to end via the API call. This also closes all open actions and starts a new session.

using Dynatrace.Xamarin;

Agent.Instance.EndVisit();

Configure data privacy (opt-in mode)

With user opt-in mode, each user of your application can set their data privacy preferences and decide whether they want or don't want to share their information. When the opt-in mode is enabled, you need to ask each user for permission to capture their data; then, you store their data privacy preferences. For details, see User opt-in mode.

Enable user opt-in mode

To activate the user opt-in mode, set the userOptIn property (Android) or DTXUserOptIn configuration key (iOS) to true in the dynatrace.config.json file.

Retrieve user's data privacy preferences

You can retrieve the data privacy preferences of a particular user.

To get the current UserPrivacyOptions configuration, use the following API call:

using Dynatrace.Xamarin;

// Get the UserPrivacyOptions object
UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();

// Get the individual settings for DataCollectionLevel and crash reporting
bool crashOptedIn = Agent.Instance.GetUserPrivacyOptions().CrashReportingOptedIn;
DataCollectionLevel dataCollectionLevel = Agent.Instance.GetUserPrivacyOptions().DataCollectionLevel;

Change user's data privacy preferences

You can adjust the data privacy preferences based on the decision of a particular user.

To set new options on a UserPrivacyOptions object, use the following code:

using Dynatrace.Xamarin;

// Creating a new UserPrivacyOptions object requires setting the two parameters of DataCollectionLevel and crash reporting
UserPrivacyOptions options = new UserPrivacyOptions(DataCollectionLevel.Performance, false);

// Update the options with the setter
// Set a data collection level (user allowed you to capture performance and personal data)
options.DataCollectionLevel = DataCollectionLevel.UserBehavior;
// Allow crash reporting (user allowed you to collect information on crashes)
options.CrashReportingOptedIn = true;

// Get the values of the configuration with the getter
options.DataCollectionLevel;
options.CrashReportingOptedIn;

// Get the UserPrivacyOptions object
UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();

To apply the new UserPrivacyOptions configuration, use this code:

using Dynatrace.Xamarin;

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

The possible values for the data collection level are as follows:

Report GPS location

You can report the latitude and longitude.

SetGPSLocation(latitude: double, longitude: double);

Configuration file

The dynatrace.config.json configuration file contains your application ID, beacon URL, and some other settings.

In summary, this results in the following order in which the configuration will be used:

The following is the dynatrace.config.json file structure for Android and iOS.

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

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

Enable OneAgent debug logs

If the instrumentation runs through and your application starts, but you see no data in your Dynatrace environment, you probably need to dig deeper to find out why OneAgents aren't sending any data. Opening up a support ticket is a great idea but gathering logs first is even better.

{
    "android": {
        "autoStart": {
            "applicationId": "<insertApplicationID>",
            "beaconUrl": "<insertBeaconURL>"
        },
        "userOptIn": true,
        "debug": {
            "agentLogging": true
        }
    }
}

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

Enable build debug logs for Android

Android only

If the Android instrumentation fails, you most likely need to open a support ticket and provide build debug logs. To provide those logs, you need to set the DynatraceInstrumentationLogging property and change the build log level to Diagnostic.

Troubleshooting

If you can't resolve a problem, check Mobile applications: Issues with Dynatrace Xamarin NuGet package in the Dynatrace Community.