microsoft / applicationinsights-xamarin

Microsoft Application Insights SDK for Xamarin

Application Insights for Xamarin.Forms (1.0-alpha.3) DEPRECATED

This SDK is officially deprecated. Please switch to HockeyApp or consider MobileCenter.

You can find more about the transition from Application Insights to HockeyApp here and about how Mobile Center will be the future of HockeyApp here.

Please don't hesitate to get in touch via [email protected]. if you have questions.

About

If you want to use the a version of the SDK, which doesn't have a dependency on Xamarin.Forms, please switch to feature/remove-xamarin-forms (Thanks to xvare). However, changes on this branch have not been fully tested, yet.

This project provides an Xamarin SDK for Application Insights. Application Insights is a service that allows developers to keep their applications available, performing, and succeeding. This SDK allows your Xamarin apps to send telemetry of various kinds (events, traces, exceptions, etc.) to the Application Insights service where your data can be visualized in the Azure Portal. Currently, we provide support for iOS and Android.

##Breaking Changes!

Version 1.0-alpha.3 of the Application Insights SDK for Xamarin.Forms comes with two major changes:

Crash Reporting and the API to send handled exceptions have been removed from the SDK. In addition, the Application Insights SDK for Xamarin.Forms is now deprecated.

The reason for this is that HockeyApp is now our major offering for mobile and cross-plattform crash reporting, beta distribution and user feedback. We are focusing all our efforts on enhancing the HockeySDK and adding telemetry features to make HockeyApp the best platform to build awesome apps. We've launched HockeyApp Preseason so you can try all the new bits yourself, including User Metrics.

We apologize for any inconvenience and please feel free to contact us at any time.

Content

1. Requirements
2. Release Notes
3. Breaking Changes & Deprecations
4. Setup
5. Developer Mode
6. Basic Usage
7. Automatic Collection of Lifecycle Events
8. Additional configuration
9. Integrate plugin sources
10. Troubleshooting
11. Contact

1. Requirements

The minimum API level to use the Application Insights SDK for Xamarin.Forms in your Android app is 9. However, automatic collection of lifecycle-events requires API level 15 and up (Ice Cream Sandwich+). For iOS builds the minimum iOS version is 6. Furthermore, the SDK has a dependency on 2.0.1.6505.

The SDK has been developed and tested with the following framework versions:

• Xamarin.Android 6.0.1.10
• Xamarin.iOS 9.4.1.25

Older versions might work, but haven't been tested.

2. Release Notes

Also see changes in older versions.

• Update underlying SDKs
  • Application Insights SDK for iOS 1.0-beta.7
  • Application Insights SDK for Android 1.0-beta.9
• Remove crash/exception reporting APIs
• Add APIs for setting common properties
• Remove API to set the userID field, add API to set the authUserID (fixes user statistics)
• Minor bugfixes

## 3. Breaking Changes & deprecations

• Remove crash reporting and APIs for exception tracking
• ApplicationInsights.SetUserId(string) changed to ApplicationInsights.SetAuthUserId(string)

## 4. Setup

We're assuming you are using Xamarin Studio to create your apps.

4.1 Add SDK to your Xamarin solution

Clone the repository in order to get the SDK sources. It contains 3 subfolder, one for a demo project (DemoApp), one for a local NuGet package (NuGet), and another one for the SDK sources (ApplicationInsightsXamarin).

There are several ways to integrate the Application Insights Xamarin SDK into your app. The recommend way is to use the NuGet-package. However, you can also integrate the SDK by importing the sources.

1. Expand one of your platform projects inside the solution panel
2. Right click the Packages folder and select Add Packages...
3. Configure a local package source and let it point to ApplicationInsightsXamarin/NuGet
4. Choose the local package source in the sources dropdown
5. Check the Show pre-release packages and select ApplicationInsights SDK for Xamarin.Forms
6. Click the Add Package button
7. Repeat those steps for all other platform projects

4.2 Configure the instrumentation key

Please see the "Getting an Application Insights Instrumentation Key" section of the wiki for more information on acquiring a key.

4.3 Add code to setup and start Application Insights

1. Depending on the plattforms you want to support, you can setup and start the Application Insights Xamarin SDK in different files:

   • Xamarin.Forms (Android & iOS): Application class (e.g. project_name.cs in the apps shared project
   • iOS only: AppDelegate.cs in your iOS platform project
   • Android only: Main Activity of your Android platform project

2. Add using statements

   using AI.XamarinSDK.Abstractions;

3. Add the following lines of code to on of the following methods

   • Xamarin.Forms (Android & iOS): OnStart ()

   • iOS only: FinishedLaunching()

   • Android only: OnStart ()

      ApplicationInsights.Setup ("<YOUR_IKEY_HERE>");
      ApplicationInsights.Start ();

   • [NOTE]: If you plan to support iOS you currently need to make a direct call to the iOS assembly so that it doesn't get stripped by the linker. Add the following line right after the Xamarin.Forms init()-call inside the FinsihedLaunching() of your AppDelegate.cs

      AI.XamarinSDK.iOS.ApplicationInsights.Init();

4. Replace <YOUR_IKEY_HERE> with the instrumentation key of your app.

Congratulation, now you're all set to use Application Insights! See Usage on how to use Application Insights.

5. Developer Mode

The developer mode is enabled automatically in case the debugger is attached or if the app is running in the emulator. This will enable the console logging and decrease the number of telemetry items per batch as well as the sending interval. If you don't want this behavior, disable the developer mode.

You can explicitly enable/disable the developer mode like this:

ApplicationInsights.SetDebugLogEnabled(false);

6. Basic Usage

The TelemetryManager provides various class methods to track events, traces, metrics, and page views. The class should only be used after ApplicationInsights has been set up & started.

//track an event
TelemetryManager.TrackEvent ("My custom event");

//track a page view
TelemetryManager.TrackPageView ("My custom page view");

//track a trace
TelemetryManager.TrackTrace ("My custom message");

//track a metric
TelemetryManager.TrackMetric ("My custom metric", 2.2);

Some data types allow for custom properties.

//Setup a custom property
Dictionary<string, string> properties = new Dictionary<string, string> ();
properties.Add ("Xamarin Key", "Custom Property Value");

//track an event with custom properties
TelemetryManager.TrackEvent ("My custom event", properties);

7. Automatic collection of life-cycle events (Sessions & Page Views)

Auto collection is enabled by default. However, you can disable automatic page view tracking & session management while setting up ApplicationInsight.

Android

To support the auto collection feature make sure the min SDK of your app is at least API level 14.

[NOTE] Only 'Activity' instances will be recognized by auto collection. Note that using e.g. Navigation.PushAsync() within a Xamarin.Forms page will replace a Fragment. However, you can programmatically track a page view in situations like this.

All plattforms

If you want to explicitly Disable automatic collection of life-cycle events (auto session tracking and auto page view tracking), call make the following calls inbetween setup and start of Application Insights.

//after ApplicationInsights.Setup(...);
ApplicationInsights.SetAutoPageViewTrackingDisabled(true);
ApplicationInsights.SetAutoSessionManagementDisabled(true);
//before ApplicationInsights.Start()

8. Additional Configuration

To configure Application Insights according to your needs, there are some other options listed here

8.1 Set User Session Time

The default time the users entering the app counts as a new session is 20s. If you want to set it to a different value, do the following:

// app background time after which session will be renewed
ApplicationInsights.SetSessionExpirationTime(30000)

8.2 Set Different Endpoint

You can also configure a different server endpoint for the SDK if needed:

ApplicationInsights.SetServerUrl("https://myServer.com/track");

8.3 Override sessionID and ID of authenticated users

Application Insights manages IDs for a session and for individual users for you. If you want to override the generated IDs with your own, it can be done like this:

ApplicationInsights.SetAuthUserId("User371263");
ApplicationInsights.RenewSession("New session ID");

[NOTE] If you want to manage sessions manually, please disable Automatic Collection of Lifecycle Events.

8.4 Setting common properties

Common properties are key-value-pairs that are added to all telemetry events, that are sent out.

// Set common properties
Dictionary<string, string> commonProperties = new Dictionary<string, string> ();
commonProperties.Add ("Common Key", "Common Property Value");
ApplicationInsights.SetCommonProperties (commonProperties);

[NOTE] Depending on the platform your are running on, the common property API behaves is slightly different. While it is possible to set those properties at any time if your app is running on iOS, you can only set common properties on Android between the Setup() and Start() call (otherwise the call will just be ignored).

## 9. Integrate plugin sources

There are several ways to integrate the Application Insights Xamarin SDK into your app. The recommend way is to use the NuGet-package. However, you can also integrate the SDK by importing the sources:

1. Copy ApplicationInsightsXamarin to your solution directory.

2. Open Xamarin Studio and add its projects to your solution. This can be done by right clicking the solution name in the solution panel, then click Add - Add Existing Project...:

   • AI.XamarinSDK
   • AI.XamarinSDK.iOS (only needed for iOS support)
   • AI.XamarinSDK.Android & AI.XamarinSDK.AndroidBindings (only needed for Android support)

   [Note] In order to successfully build the SDK, you may have to update all referenced packages. Simply right click on the Packages folder of each of those projects and click Update.

3. Add references to your app projects

   • Android

     1. In the solution panel, select the Android app project.
     2. In the main menu go to Project - Edit References.
     3. Select the All tab and check AI.XamarinSDK.Android.
     4. Confirm the change by clicking the OK button.

   • iOS

     1. In the solution panel, select the iOS app project.
     2. In the main menu go to Project - Edit References.
     3. Select the All tab and check AI.XamarinSDK.iOS.
     4. Confirm the change by clicking the OK button
   4. Follow instructions in 4.2..

## 10. Troubleshooting

SDK references broken

In order to successfully build the SDK, you may have to update all referenced packages. Simply right click on the Packages folder of each of those projects and click Update.

iOS App crashes immediately after start

If you plan to support iOS you currently need to make a direct call to the iOS assembly so that it doesn't get stripped by the linker. Add the following line right after the Xamarin.Forms init()-call inside the FinsihedLaunching() of your AppDelegate.cs

AI.XamarinSDK.iOS.ApplicationInsights.Init();

## 11. Contact

If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to open a GitHub issue here or contact us at [email protected]

applicationinsights-xamarin's Issues

Release on NuGet

Please release the current version(s) on NuGet so we can use VSTS build agents.

Why isn't this on NuGet?

You've made a Nuspec, why is this not published on NuGet? Why do I have to build it myself?

Missing nupkg file in release v1.0 alpha 3

The Microsoft.ApplicationInsights.Xamarin.1.0.0-alpha3.nupkg file is missing from the ApplicationInsightsXamarinSDK\NuGet folder thus preventing installation from NuGet.

Use Application Insights without Xamarin Forms

Hi,
I wanted to use Application Insights in an iOS project without Xamarin Forms. It seems like this is currently not possible, is there a valid workaround?

How to use StartNewSession and SetUserId?

Do we use StartNewSession() in place of Start()?
And can SetUserId() be called at any time or does it need to be called before Start()?
Also, how do we get authenticated users to show up in the AI dashboard as explained in the JS version here https://azure.microsoft.com/en-us/documentation/articles/app-insights-web-track-usage/ (see authenticated users section). Is this possible in the Xam platform version?

Thanks.

1.0-alpha3 does not build on Xamarin.Forms 2.3.2.127

When creating a new project with Xamarin.Forms 2.3.2.127, as soon as you add Application Insights alpha3 the Android project just breaks and won't build anymore. If you remove Application Insights you can build the project successfully again.
I tested this with the local NuGet package.

All the errors are related to Resource.designer.cs file, like this one:

CS0117    'Resource.Styleable' does not contain a definition for 'Theme_actionBarSplitStyle'    demo_xamarin.Droid    C:\Users\x\Documents\Pessoal\Xamarin_Projects\demo_xamarin\demo_xamarin\demo_xamarin.Droid\Resources\Resource.Designer.cs

There are more than 150 errors, all related to this file.

I've tried many, many things, until I suspected the problem was the Insights package.

Does Application Insights work with Forms newer than 2.0.1.6505?

If that's the case, I think this should be more explicit on the README:

Furthermore, the SDK has a dependency on 2.0.1.6505

does not seem very clear to me. Newcomers might not understand you are talking about Forms version, and might assume this is a minimum dependency, and not hard dependency.

Are Xamarin.Forms PCL projects supported?

When trying to add AI to a Xamarin.Forms PCL project, I get:

Adding Microsoft.ApplicationInsights.Xamarin...
Attempting to resolve dependency 'Xamarin.Forms (≥ 1.4.3.6374)'.
Adding 'Microsoft.ApplicationInsights.Xamarin 1.0.0-alpha2' to XFStreamingAudio.
Could not install package 'Microsoft.ApplicationInsights.Xamarin 1.0.0-alpha2'. You are trying to install this package into a project that targets 'portable-net45+win+wp80+MonoTouch10+MonoAndroid10+xamarinmac20+xamarinios10', but the package does not contain any assembly references or content files that are compatible with that framework. For more information, contact the package author.

My Xamarin.Forms PCL targets profile 78.

Does this SDK work with PCLs?

Missing Com.Microsoft.Applicationinsights.Library.ApplicationInsights

I am trying to rebuild the solution to fix the TrackMetric properties issue I ran across however I am missing the reference Com.Microsoft.Applicationinsights.Library.ApplicationInsights and cannot for the life of me figure out how to get it added.

Any assistance would be appreciated.
Thanks
M

Upload dsym file

Is there a way to upload the dsym file to Application Insights? Currently my crash stack traces are not very informative and I think this results from the fact that the system doesn't have the dsym available.

The following stack trace is shown in Application Insights:
SIGTRAP
libdyld.dylib
MobileClient.IOS
MobileClient.IOS
MobileClient.IOS
MobileClient.IOS
MobileClient.IOS
MobileClient.IOS
MobileClient.IOS
???
???
???
???
[...]

About Exception reporting APIs

I noticed the last versions of Application Inisghts removed support for exceptions reporting in favor to HockeyApp. The problem is that HockeyApp for Xamarin still doesn't support (known) exception reporting, only crashes.

So right now users don't have a way of doing that, since everyone (Xamarin Insights and AppInsights) is dropping support and telling us to use a feature that isn't available yet on HockeyApp SDK for Xamarin.

What is the recommended way for doing this now? Would Application Insights consider putting back the exception APIs until HockeyApp releases a more complete version of the SDK for Xamarin?

ApplicationInsights is not working in Xamarin.iOS App

Hi,

I'm really rather confused how I can get this library working in a Xamarin.iOS (not forms) app. I've tried several things with no luck on every branch here.

I am currently on the branch "Xamarin (1.0-alpha.3)" where the dependency on Xamarin.Forms was removed (I realise this hasn't been thoroughly tested). However, I am unable to follow the instructions in the Readme as CrossApplicationInsights does not exist in the namespace AI.XamarinSDK.

I have also tried following the instructions on the Master branch but that uses AI.XamarinSDK.Abstractions which causes a runtime error saying Xamarin.Forms isn't referenced.

Another thing I've also tried is referencing like this AI.XamarinSDK.iOS.MSAIApplicationInsights.Setup("******"); but that crashes silently at runtime with no exception.

Any pointers as to where I'm going wrong would be appreciated.

James

Null reference exception

I get a Null reference exception in the second line:

1- MainPage.Navigation.InsertPageBefore();
2 -await MainPage.Navigation.PopAsync();

After adding this line:

ApplicationInsights.SetAutoPageViewTrackingDisabled(true);

I dont see the exception anymore

How do I build?

So, I got the feature zip with no forms dependency and I'm trying to build it.
I get this when trying to build the iOS version:

1>X:\ApplicationInsightsXamarinSDK\ApplicationInsightsXamarin\AI.XamarinSDK.iOS\TelemetryManager.cs(11,34,11,51): error CS0012: The type 'Dictionary<,>' is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Collections, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.
1>X:\ApplicationInsightsXamarinSDK\ApplicationInsightsXamarin\AI.XamarinSDK.iOS\TelemetryManager.cs(11,34,11,51): error CS0012: The type 'Exception' is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Runtime, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.

And the Android version give me this:

1>X:\ApplicationInsightsXamarinSDK\ApplicationInsightsXamarin\AI.XamarinSDK.Android\TelemetryManager.cs(7,21,7,40): error CS0234: The type or namespace name 'Applicationinsights' does not exist in the namespace 'Com.Microsoft' (are you missing an assembly reference?)

How do I fix these so I can build?

Thanks.

How to use this in project Xamarin.Forms Portable?

When you try to install the Nuget package, I get the error:

Could not install package 'Microsoft.ApplicationInsights.Xamarin 1.0.0-alpha2'.
You are trying to install this package into a project that targets '.NETPortable,Version=v4.5,Profile=Profile78',
but the package does not contain any assembly references or content files that are compatible with that framework.

Can I use ApplicationInsights in a Portable project?

Crash reports are created and sent but don't show up in Azure's portal (iOS)

Hi,

I created an Application Insights resource in Azure's portal (ApplicationType="iOS Application").
Using the provided instrumentation key, I initialized ApplicationInsights as described in the readme.

I do get some telemetry in the Azure web portal (Users, sessions, page views) but I don't get any crash report.

I crash with a simple NullReferenceException when I click a button:

string name = null;
int i = name.Length;

The app does crash and I can see that a report is created in the simulator's filesystem at:
Library/Application Support/com.microsoft.ApplicationInsights/highPrio

When I start the application then the report disappears (I guess it is sent to Azure) but never shows up in the statistics in the web portal.
I get either "0 crashes":

... or a message mentioning that I have to configure crash reporting:

The read.me file does not mention anything about crash reporting configuration, it says it is enabled by default.

Did I miss something?

Furthermore, the app seems to freeze instead of crashing the second time I make the crash occur.

Regards,

---

Xamarin Studio Version 5.9.5 (build 9)
Xcode 6.4 (7720) Build 6E35b
Xamarin.iOS Version: 8.10.4.46 (Business Edition)
Xamarin.Android Version: 5.1.5.3 (Business Edition)
Mac OS X 10.10.5

Create a Nuget Package

an official nuget package would be really great and would make much easier.

Add support for Xamarin.Mac

In addition to iOS and Android, please support Xamarin.Mac.

Xamarin Android not Logging Telemetry

We able to integrate Applicaiton insights in the xamarin forms and able to get the telemetry for iOS. Same not working with Android. When we run android on output below message is showing

05-17 16:57:11.153 W/art ( 677): JNI RegisterNativeMethods: attempt to register 0 native methods for md531a9393487f6e844970cf7436e0f56cf.ApplicationInsights 05-17 16:57:11.153 D/Mono ( 677): Assembly Ref addref AI.XamarinSDK.Android[0xaefd69a0] -> Xamarin.Forms.Platform.Android[0xaee2db20]: 7 05-17 16:57:11.153 D/Mono ( 677): Assembly Ref addref AI.XamarinSDK.Android[0xaefd69a0] -> AI.XamarinSDK.AndroidBindings[0xaefd6760]: 2 05-17 16:57:11.223 D/Mono ( 677): Assembly Ref addref ODISMember.Services[0xaee2a880] -> AI.XamarinSDK.Abstractions[0xaefd67c0]: 4 05-17 16:57:11.223 I/System.out( 677): Sending Operation Instance 1 05-17 16:57:16.768 W/art ( 677): JNI RegisterNativeMethods: attempt to register 0 native methods for md531a9393487f6e844970cf7436e0f56cf.TelemetryManager 05-17 16:57:16.823 D/OpenGLRenderer( 677): Render dirty regions requested: true 05-17 16:57:16.998 I/ ( 677): PLATFORM VERSION : JB-MR-2 05-17 16:57:17.003 I/OpenGLRenderer( 677): Initialized EGL, version 1.4

How can we fix this strange issue. We used both motorola andsamsung devices which all below the verion of 5.0.1 and below

Reuse de PCL implementation instead of a new one

Hi,

I have recompiled the PCL implementation for dotnet adding targets for Xamarin and it works. Why a new implementation is required instead of creating extensions for iOS and Android?

Thanks!

Why is Xamarin.Forms a dependency?

I wan't to add ApplicationInsights to a Xamarin.iOS project which does not use Xamarin.Forms. I do not want to pull in Xamarin.Forms in as a dependency. I don't see a need for this.

Fails to report statistical data on Android (400 Bad request)

Hi,

Today I gave yet another chance to Application Insights and got the following debug log when the SDK tries to send telemetry to Azure on an Android Xamarin.Forms application:

[com.microsoft.applicationinsights.logging Sender] Logging payload:[{"ver":1,"name":"Microsoft.ApplicationInsights.PageView","time":"2015-10-07T13:55:34.846Z",...}]
[com.microsoft.applicationinsights.logging Sender] response code:400
[com.microsoft.applicationinsights.logging Persistence] Successfully deleted telemetry file :/data/data/com.my.domain.my.app/files/com.microsoft.applicationinsights/regularpriority/49d7d644-7ddf-4c3d-952b-64e79336cc83
[com.microsoft.applicationinsights.logging Sender] Unexpected response code: 400

And no statistics appear in the Application Insight dashboard in Azure's portal.

I'd be thankful to know if someone is working on these issues (this one and issue #9) or if I should turn myself toward other products.

Regards,

Thibault D.

Profile49

Hi,

I can see that AI.XamarinSDK.Abstractions.csproj targets Profile49.
Is there any reasons why the SDK can't support WPA81 and Windows platforms, and use profile 78 or 259 instead?

Regards,

Duplicate PageView events on iOS

I have downloaded and started using this sdk.
I am getting duplicate events for PageView events in the portal. I started looking at the raw data (as I export it to Azure Table Storage), I could see that the SDK is sending the same page view events twice for each event.

Any idea of what is happening? Your help would be highly appreciated.