Xamarin Insights

简介：

Xamarin Insights 包括两部分：NuGet package和Web Portal。NuGet包可以使任何手机或桌面应用程序调用它提供的接口来记录exception、event、time tracking信息，在不联网的情况下写到本地文件（联网时再上传到服务器），联网时直接上传到服务器；Web Portal可以查看客户端上传的应用程序分析结果或崩溃报告。



注意：

1> InSights客户端可以在Debug、Release、Simulator、App Store等环境下收集数据。

2> InSights客户端支持的平台包括：Xamarin.IOS、Xamarin.Android（API level 15 and above）、Windows Phone 8.0Sliverlight、Windows Phone & Windows 8.1（winRT）、Xamarin.Mac、Windows Form（>=NET 4.0）、Xamarin.Mac2。



步骤：

一、 Application Registration（应用程序注册）
在应用程序实现Xamarin InSights、执行分析和崩溃报告之前，必须在Xamarin InSights Web Portal进行注册。

1> 在浏览器中输入网址：insights.xamarin.com，浏览XamarinInSights Web Portal。

2> 使用Xamarin Developer email and user ID登陆Web Portal，登陆成功后，如下图所示。



3> 单击“Add New App”出现如下图所示网页。

4> 在“App Name”下面输入你的应用程序名称（例如：XdfNfc）。

5> 复制“Copy the Api Key”下方的key，稍后，我们在应用程序中初始化Xamarin InSights时，需要用到该key。

6> 滚动到屏幕的最下方，点击“Create new app”，完成注册步骤。

二、 Installing the XamarinInsights NuGet
当应用程序在Web Port注册后，接下来需要在项目中安装Xamar inInsights NuGet。

1> 工具—>NuGet程序包管理器—>程序包管理器控制台。

2> PM> Install-PackageXamarin.Insights。

三、 Application Registration andSetup（应用程序注册与配置）
在从应用程序收集分析和崩溃报告前，需要用key(即在第一步在web Portal中复制的)在程序中注册Xamarin InSights（在不同的平台上使用Xamarin InSights NuGet注册应用程序的步骤也不同，下面以Xamarin.Android为例进行讲解）。

1>注册

在程序中引入XamarinInSights后，注册的步骤需要在Launch Activity的OnCreate方法中执行（Alternatively, if a singleton model is being employed, theregistration can called from there）。将下方代码加入LaunchActivity的OnCreate方法中。
using Xamarin;
...
Insights.Initialize("Your API key",yourAppContext);
2>必选权限:除了注册API Key 之外，为了使XamarinInSights正常的工作，我们需要为之设置权限，Xamarin Insights需要INTERNET权限，该权限使设备可以使用Internet发送日志数据到服务器。
3> 可选权限：下面列出的选择性权限可以增强Xamarin Insight的功能。
l ACCESS_NETWORK_STATE & ACCESS_WIFI_STATE –在通信之前优先检查网络状态
l READ_EXTERNAL_STORAGE – 检查任何external storage的大小以及剩余空间
l BATTERY_STATS – 在发送报告之前优先检查电池电量
l READ_PHONE_STATE – 允许得到deviceid
l READ_LOGS & BIND_NOTIFICATION_LISTENER_SERVICE –读取Android本身的崩溃报告，这样不仅可以向服务器发送.NET exception，而且可以发送Android runtime exception（Androidruntime exception包括java runtime，不包括Xamarin.Android）
四、 （Identifying the Device User）识别设备用户
当我们使用Xamarin InSights 从应用程序中收集分析和崩溃报告时，我们可以选择性的识别设备上应用程序的用户身份。当然，这也不是必须的，拥有用户的身份后，你可以联系他们而重现bug或者从他们那里的到应用程序性能的反馈。
Xamarin InSights提供了两个可用的方法来识别一个用户：Basic or Advanced（在应用程序中，你可以在任何时间甚至是多次识别用户的身份，而不用担心客户端与服务端的多次传输，因此你应该在最合适的时候来调用该接口，为了方便，下面的例子在调用了“Insights.Initialize”之后增加了该接口的调用）。
1>Basic Identification
Insights.Initialize("YourAPI key", yourAppContext);
Insights.Identify("UniqueUser ID", "Key", "Value");
l Unique User ID – 一个唯一的识别码（例如：用户登录系统的ID）
l Key – 量词（例如：Name、Email、Phone等等）
l Value – Key的值
2>Advanced Identification
Insights.Initialize("YourAPI key", yourAppContext);
var manyInfos = newDictionary {
{"Email","john.doe@company.com"} ,
{"Name", "JohnDoe"}
}
Insights.Identify("UniqueUser ID", manyInfos);
该方法中的Dictionary提供了更多的信息来识别用户（例如用户的全名，Email地址等）
3>GuestIdentities
Insights默认将用户识别为Guest，除非你在代码中调用了Insights.Identify方法，在调用了Insights.Identify方法后，如果想恢复Guest身份，可以使用下面的API。
Insights.Identify(Insights.Traits.GuestIdentifier, null);
五、 Logging Reportsto Xamarin Insights（记录报告、发送给服务端）
安装Xamarin InSights、在程序中初始化之后，有很多方法可以发送分析和崩溃报告到服务端。
1> Catching Exceptions：运行Xamarin InSights程序时，服务端将捕获应用程序生命周期中所有的异常，当异常发生时，将会被发送给服务端（在联网的前提下或者程序下次启动时）。
1.1> Outside of a Try/Catch Enclosure
Try/Catch块外的异常发生时，所有的异常被发送给服务端，但是这些异常信息中没有内在的错误详情，这样会使用户发送给服务端的数据量增大，但是没有给出导致这些异常抛出的具体信息。
1.2> Inside of a Try/Catch Enclosure
通过使用try/catch块，可以限制发送给服务端的信息量，减少服务端对崩溃和设备状态作出的图表分析量。
使用try/catch块的好处：
l 应用程序更加稳定；
l 给服务端发送的报告更加精确；
l 给服务端发送的报告有详细的附加信息；
1.3> Simple Exception Catching（只捕捉异常对象）
可以在代码中添加try/catch块来实现只捕捉异常对象，代码如下所示：
try
{
int divByZero = 42 / int.Parse("0");
}
catch (DivideByZeroException ex)
{
Insights.Report(ex);
}
发送给服务器的异常信息是整个DivideByZeroException对象，这样编写代码与不加try/catch块并引发异常时发送给服务器的信息是一样的。
1.4> Adding Additional Information to Exception Catching（给异常捕捉添加附加信息）
接下来演示如何通过添加附加信息来减少发送给服务器的异常报告量：
try
{
using (var text =File.OpenText("saved_game001.txt"))
{
Console.WriteLine("{0}", text.ReadLine());
...
}
}
catch (FileNotFoundException ex)
{
Insights.Report(ex, new Dictionary<string,string>
{
{ "Filename", "saved_game001.txt" },
{ "Where", "Reload game" },
{ "Issue", "Index of available games iscorrupted" }
});
}
这样整个异常对象仍然会发送给服务端，同时，带有debug附加信息的Dictionary也会被发送给服务端，我们可以发送任何有助于跟踪bug的键值对。
1.5> Allowing an Exception and Reporting Additional Information（允许异常继续抛出、报告附加信息）
如果我们希望允许异常的继续抛出并且想要给异常报告附加信息，我们可以使用Exception.Data属性。
try {
ExceptionThrowingFunction();
}
catch (Exception exception) {
exception.Data["AccountType"] ="standard";
throw;
}
这里我们使用键值对来给异常报告附加信息并且允许异常的继续抛出。
1.6> Disabling Uncaught Exception Reporting（不发送在try/catch块外的异常报告）
l 有些情况下，我们不希望发送未被捕捉的异常信息（即在try/catch块外的异常）给服务器，可以添加下行代码满足此情况：
Insights.DisableExceptionCatching = true;
设置该属性后，任何在Try/Catch块外引发的异常都不会被记录，如果想恢复记录任何异常的状态，只需将属性Insights.DisableExceptionCatching重新设置为false。
l 设置属性Insights.DisableExceptionCatching为true后，仍想记录try/catch块外的异常，可以添加下行代码：
Xamarin.Insights.Save();（该方法只在属性DisableExceptionCatching为true时，并且想记录try/catch块外的异常时使用）
1.7> Debug Mode（Insights的debug模式）
你会发现在debug程序的时候，InSights会成为我们的障碍，因为它会捕捉我们想查看的（原生的或是手动设置的）崩溃报告。这种情况下我们可以使用InSights的debug模式，将初始化InSights的代码改为如下行代码所示：
Insights.Initialize(Insights.DebugModeKey);
在InSights的debug模式下，不会收集未被处理的崩溃报告、原生的崩溃报告以及任何Insights.Track()或者Insights.Identify()方法的调用也将会被忽略。
1.8> Dealing with Startup Crashes（处理启动时崩溃）
在某种程度上，应用程序启动时崩溃没有留足够的时间给Insights传输崩溃报告，Insights有特的机制处理这个问题：
Insights.HasPendingCrashReport += (sender,isStartupCrash) =>{
if (isStartupCrash) {
Insights.PurgePendingCrashReports().Wait();}};
Insights.Initialize("Your API Key");
这个API会在Insights检测到一个即将发生的崩溃报告时给程序一个通知，并调用Insights.PurgePendingCrashReports();当向服务器发送这些崩溃报告时，允许你阻塞方法，这样会延迟app的启动时间，这也是这个可选API被自动替换的原因。在事件委托中的isStartupCrash值将通知你在应用程序启动时，崩溃会不会在5秒内发生，一般情况下，这个值表示app在启动时崩溃了。
1.9> Short Lived Desktop Applications
对于短生命周期的应用程序，比如命令行程序，可以调用Insights.PurgeAllPendingData().Wait()以保证在app结束之前发送数据给服务器。
2> SwitchingXamarin Insights On or Off（开启、关闭XamarinInsights）
有些情况下，不想讲数据发送到服务端，比如：电量低、任务紧……
Start():开启Xamarin Insights;
Stop():停止Xamarin Insights;
这两个方法可以在任何时候调用。
3> TrackingApplication Events
Xamarin Insights除了可以记录异常报告外，还可以被用来追踪程序事件，比如：用户使用了程序的某个功能、追踪执行这个功能使用的时间、某个功能是否从来未被使用过或是这个功能很难被发现。
下面我们将演示给应用程序添加event（事件）或timetracking（时间跟踪）：
1.
3.1> Implementing Event Tracking
可以使用方法Insights.Track来跟踪app中的某个功能，并发送信息给服务器。比如：应用程序中有播放音乐功能，当指定歌曲播放的时候，我们可以添加下列代码来创建一个事件：
Insights.Track("MusicTrackPlayed",new Dictionary <string,string>{
{"TrackID","E1D8AB93"},
{"Length", "183"}
});
MusicTrackPlayed是事件的唯一标识，Dictionary提供了播放歌曲的详细信息，通过这个方法，我们可以想服务器发送任何类型的事件（注意：一个Insights.Track一次可以发送的数据量为1024 characters，超过部分将被忽略、不被发送）。
3.2> Implementing Time Tracking
程序中一个任务执行所需的事件对终端用户体验有很大的影响，比如：如果程序花费了很长的时间来完成一个任务，用户可能会认为程序已经锁定或者宕机。
接下来用下列代码演示如何向服务器发送任务执行时间的报告：
using (var handle =Insights.TrackTime("TimeToLogin")) {
await SubmitLoginInformation("myuserid","mypassword");
// ... more code goes here ...
}
上面的代码是在Insights.TrackTime的内部完成了时间的跟踪，当然，也可以将代码写成如下所示：
// or if you do not wish to use the using syntax
var handle = Insights.TrackTime("TimeToLogin");
handle.Start();
await SubmitLoginInformation("myuserid","mypassword");
// ... more code goes here ...
handle.Stop();
无论使用哪中写法，当时间跟踪任务完成后，时间日志将会被发送到服务端。
3.3> Difference between Track and TrackTime
方法Insights.Track()和方法Insights.TrackTime ()的区别在服务端，虽然这两个方法类似，Track()方法只是跟踪分析过程，而TrackTime可以在Web Portal端查看日志数据时使用时间图表工具。在跟踪服务器响应时间、程序性能监控时可以使用TrackTime方法。
4> CommunicationPreferences
基于程序的需要，你可以选择性的向服务器发送某种类型的数据，例如：是否发送try/catch块外的异常。
Insights.DisableCollection = true; // Disables Insightsautomated behaviors
Insights.DisableDataTransmission = true; // Disables datacommunication with the _webapi_
Insights.DisableExceptionCatching = true; // Disablesautomatic unhandled exception catching
Insights.DisableCollectionTypes = Insights.OSInfo; //Stops Insights from tracking OSInfo
Insights.DisableCollectionTypes = Insights.Jailbroken; //Stops Insights from tracking HardwareInfo
Insights.DisableCollectionTypes = Insights.NetworkInfo;// Stops Insights from tracking NetworkInfo
DisableCollection – 该值设置为true，Insights将停止收集信息.
DisableDataTransmission – 该值设置为true，Insights将停止想服务端发送信息，可以在cpu占用率高、电池电量低时使用该属性.
DisableExceptionCatching - 该值设置为true，Insights将停止捕捉try/catch块外的异常.
DisableCollectionTypes:
l Insights.OSInfo – 停止跟踪app使用的操作系统信息.
l Insights.Jailbroken – 停止跟踪app使用的硬件设备信息.
l Insights.NetworkInfo – 停止跟踪app使用的network信息.
这些DisablecollectionTypes类型可以使用符号“|”连接起来使用，例如：
Insights.DisableCollectionTypes= Insights.OSInfo | Insights.NetworkInfo;