ApplicationInsights-OSX 1.0-beta.2

您想在 Podfile 中添加类似以下的内容

target 'MyApp' do
  pod 'ApplicationInsights-OSX', '1.0-beta.2'
end

然后在您的终端或从 CocoaPods.app 中运行 pod install

或者为了测试运行，运行以下命令

pod try ApplicationInsights-OSX

ApplicationInsights-OSX 1.0-beta.2

由
Microsoft

此库已弃用。

Mac 应用 Application Insights (1.0-beta.2)

这是 Application Insights Mac SDK 的仓库。 Application Insights Application Insights 是一项让开发者能够保持其应用程序可用、表现良好并取得成功的服务。 SDK 使您能够将各种类型的遥测数据（事件、跟踪、页面视图等）发送到 Application Insights 服务，您可以在 Azure 门户中可视化您的数据。

您可以使用 Mac 应用 Application Insights 工具将 Application Insights Mac SDK 集成到您现有的应用程序中。 SDK 在运行 OS X 10.8 或更高版本的设备上运行。您需要 Microsoft Azure 的订阅。（在您想发送大量遥测数据之前是免费的。）

Application Insights 概述

SDK 在 OS X 10.8 或更高版本的设备上运行。

重大更改！

Application Insights for Mac 的 1.0-beta.2 版本有两个主要变更

从 SDK 中删除了崩溃报告和发送已处理异常的 API。此外，Application Insights for Mac SDK 现已弃用。

原因是 HockeyApp 现在我们为移动和跨平台崩溃报告、预发布分发和用户反馈的主要产品。我们正集中所有精力增强 HockeySDK 并添加遥测功能，使 HockeyApp 成为构建优秀应用程序的最佳平台。我们可以启动 HockeyApp Preseason，您可以自己尝试所有新功能，包括用户指标。

我们对任何不便深感抱歉，请随时通过联系我们。

1. 发布说明

移除崩溃报告功能。要为您的应用程序添加此功能，我们建议使用 HockeyApp，它提供了优质的崩溃报告、反馈、测试版分发等功能。
修复了一个问题：页面视图持续时间错误地以天为单位发送，而不是以 'd:hh:mm:ss.fffffff' 格式的字符串发送。相关方法现在接受以秒为单位的 NSTimeInterval 参数。
修复会话管理与一些小错误

有关以前版本的发布说明，请参阅此处。

2. 要求

SDK 在 OS X 10.8 或更高版本的设备上运行。

3. 设置

我们建议将我们的二进制文件集成到您的 Xcode 项目中，为您在OS X应用程序中设置 Application Insights。有关设置 SDK 的其他方法，请参阅高级设置。同时，确保您的应用程序已签名，因为 SDK 正在将数据写入密钥链。未沙盒或未签名的应用程序将在应用程序启动时出现密钥链对话框！

您可以使用 Application Insights for Mac 工具来集成 SDK，该工具为该过程提供了一个分步向导。如果您想手动集成 SDK，可以按照以下步骤进行

3.1 获取一个 Instruments 密钥

要查看您的遥测数据，您需要在 Microsoft Azure Portal 中有一个 Application Insights 资源。您可以选择：

创建新资源；或者
如果您的应用程序使用 Web 服务，请使用您之前设置的与该 Web 服务相同的资源。请参阅 ASP.NET 或 J2EE 的设置。

打开您的资源并在“基本”下拉菜单中打开。不久，您将需要复制 Instruments 密钥。

3.2 下载 SDK

下载最新版本的 Application Insights for OSX 框架，该框架被提供给 zip 文件。
解压缩文件，您将看到一个名为 ApplicationInsights 的文件夹。

3.3 在 Finder 中将 SDK 复制到您的项目目录中

根据我们的经验，第三方库通常位于一个子目录中（让我们将这个子目录称为 Vendor），所以如果您没有为库设置子目录，现在是一个很好的开始。以我们的例子为例，在项目目录中创建一个名为“Vendor”的文件夹，并将解压缩的 ApplicationInsights 文件夹移动到其中。

3.4 在 Xcode 中设置 SDK

我们建议使用 Xcode 的组功能创建一个第三方库组，类似于磁盘上的文件结构。例如，类似于 3.1 中的文件结构，我们的项目具有称为 Vendor 的组。
确保 项目导航器 是可见的（⌘+1）
从 Finder 中的窗口将 ApplicationInsights.framework 拖放到 Xcode 中的项目，并将其移动到 项目导航器 中所需的位置（例如，移动到名为 Vendor 的组中）
会出现一个弹出窗口。选择 为任何添加的文件夹创建组，并为您的目标勾选复选框。然后点击 完成。
在 项目导航器 中选择您的项目（⌘+1）。
选择您的应用程序目标。
选择 构建阶段 选项卡。
- 点击顶部的 + 按钮，然后选择 添加复制文件。
- 点击新构建阶段旁边的展开三角形。
- 从目标列表中选择 框架。
- 将 ApplicationInsights.framework 从 项目导航器 拖到新的复制文件阶段列表中。
打开您的应用程序目标中的 Info.plist 文件，并添加一个类型为 字符串 的新字段。将其命名为 MSAIInstrumentationKey，并将您的应用程序洞察仪器密钥设置为它的值。

3.5 修改代码

Objective-C

打开您的 AppDelegate.m 文件。
在文件的顶部，在您的 import 语句下方添加以下行。
```
#import <ApplicationInsightsOSX/ApplicationInsights.h>
```
搜索方法 application:didFinishLaunchingWithOptions:。

添加以下行来设置和启动应用程序洞察 SDK。

// Setup Application Insights SDK
[[MSAIApplicationInsights sharedInstance] setup];
// Do some additional configuration if needed here
...
[[MSAIApplicationInsights sharedInstance] start];

您还可以使用以下快捷方式：

[MSAIApplicationInsights setup];
[MSAIApplicationInsights start];

Swift

打开您的 AppDelegate.swift 文件。
在文件的顶部，在您的 import 语句下方添加以下行。
```
import ApplicationInsightsOSX
```

搜索方法

func applicationDidFinishLaunching(_ aNotification: NSNotification)

添加以下行来设置和启动应用程序洞察 SDK。

MSAIApplicationInsights.sharedInstance().setup()
MSAIApplicationInsights.sharedInstance().start()

您还可以使用以下快捷方式：

MSAIApplicationInsights.setup()
MSAIApplicationInsights.start()

恭喜，现在您已经准备好使用应用程序洞察了！有关如何使用应用程序洞察的信息，请参阅基本用法。

4. 高级设置

4.1 在代码中设置仪器密钥

您也可以在代码中设置应用程序的仪器密钥。这将覆盖您可能在 Info.plist 中设置的一个。要设置它，MSAIApplicationInsights 提供了一个重载构造函数。

[MSAIApplicationInsights setupWithInstrumentationKey:@"{YOUR-INSTRUMENTATIONKEY}"];


//Do additional configuration

[MSAIApplicationInsights start];

4.3 Mac 扩展

以下是一些使用 OS X 扩展与应用程序洞察 SDK 一起使用时需要考虑的点。

每个扩展都需要使用与主应用程序相同的版本（CFBundleShortVersionString）和构建号（CFBundleVersion）。（这仅在您为应用程序和扩展使用相同的 MSAIInstrumentationKey 时是必需的）。
您需要确保 SDK 设置代码只调用一次。由于没有 applicationDidFinishLaunching: 相当的方法，并且 viewDidLoad 可以多次运行，因此您需要使用如下示例所示的设置。

@interface TodayViewController () <NCWidgetProviding>
@property (nonatomic, assign) BOOL didSetupApplicationInsightsSDK;
@end

@implementation TodayViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    if (!self.didSetupApplicationInsightsSDK) {
        [MSAIApplicationInsights setup];
        [MSAIApplicationInsights start];
        self.didSetupApplicationInsightsSDK = YES;
    }
}

5. 开发者模式

5.1 数据批量处理

如果附加了调试器或者应用程序正在模拟器中运行，则自动开启 开发者模式。这将减少每次批量发送的遥测项数量（5 个项）以及遥测发送的时间间隔（3 秒）。

5.2 记录日志

我们都是清洁调试输出的粉丝，不喜欢第三方 SDK 消息在调试视图中堆积，对吧？！这就是为什么应用程序洞察仅在开发者在启动 SDK 之前明确启用调试日志时，才会保留最少的日志消息（如关键错误）。

[MSAIApplicationInsights setup]; //setup the SDK

[[MSAIApplicationInsights sharedInstance] setDebugLogEnabled:YES]; //enable debug logging 

[MSAIApplicationInsights start]; //start using the SDK

如果应用在应用商店环境中运行，此设置将被忽略，所以用户的控制台不会因我们的日志信息而杂乱无章。

6. 基本用法

[注意] SDK 经过优化，尽可能推迟所有操作，并确保在例如启动时崩溃也可以被捕获，每个模块在延迟几秒后执行其他代码。这确保了 applicationDidFinishLaunching: 会尽可能快地处理，SDK 不会阻塞启动序列，从而可能导致看门进程杀死它。

您已按照上述描述设置 SDK 后，MSAITelemetryManager-实例是跟踪事件、跟踪、指标或页面视图的中心接口。

有关如何使用 API 并在 Application Insights 资源中查看结果的整体介绍，请参阅API 概述。示例中使用 Java，但原理相同。

6.1 Objective-C

// Send an event with custom properties and measurements data
[MSAITelemetryManager trackEventWithName:@"Hello World event!"
                              properties:@{@"Test property 1":@"Some value",
                                           @"Test property 2":@"Some other value"}
                            measurements:@{@"Test measurement 1":@(4.8),
                                           @"Test measurement 2":@(15.16),
                                           @"Test measurement 3":@(23.42)}];

// Send a message
[MSAITelemetryManager trackTraceWithMessage:@"Test message"];

// Manually send page views (duration 200 ms) 
[MSAITelemetryManager trackPageView:@"MyViewController"
                           duration:0.2
                         properties:@{@"Test measurement 1":@(4.8)}];

// Send custom metrics
[MSAITelemetryManager trackMetricWithName:@"Test metric" value:42.2];

6.2 Swift

// Send an event with custom properties and measuremnts data
MSAITelemetryManager.trackEventWithName("Hello World event!", 
                                  properties:["Test property 1":"Some value",
                                              "Test property 2":"Some other value"],
                                measurements:["Test measurement 1":4.8,
                                              "Test measurement 2":15.16,
                                              "Test measurement 3":23.42])

// Send a message
MSAITelemetryManager.trackTraceWithMessage("Test message")

// Manually send pageviews (duration 200 ms)
MSAITelemetryManager.trackPageView("MyViewController",
                                   duration:0.2,
                                 properties:["Test measurement 1":4.8])

// Send a message
MSAITelemetryManager.trackMetricWithName("Test metric", value:42.2)

在门户中查看您的数据

在 Azure 门户中，打开创建以获取您的工具条密钥的应用程序资源。您将看到显示页面视图和会话计数的图表。要查看更多

单击任何图表以查看更多详情。您可以为创建自己的指标页面，设置警报，并过滤和分段您的数据。
单击搜索以查看单独的 trackEvent，trackTrace 和 trackPageView 消息。

7. 高级用法

SDK 还允许一些更高级的用法。

7.1 共同属性

还可以设置所谓的“共同属性”，然后它们将被自动附加到所有遥测数据项上。

Objective-C

[MSAITelemetryManager setCommonProperties:@{@"custom info":@"some value"}];

Swift

MSAITelemetryManager.setCommonProperties(["custom info":"some value"])

通过属性筛选视图

使用属性来分段和过滤指标图表，并过滤搜索。

8. 自动收集生命周期事件

生命周期事件的自动收集默认是启用的。这意味着 Application Insights 会自动为您管理会话。

8.1 会话

默认情况下，Mac 版的 Application Insights 会在包含的应用程序重新启动时（这意味着“冷启动”，即应用程序在启动之前未在内存中）或当应用程序在后台运行超过 20 秒时启动一个新会话。

您可以选择更改这个时间段

[MSAIApplicationInsights setAppBackgroundTimeBeforeSessionExpires:60];

完全关闭自动会话管理

[MSAIApplicationInsights setAutoSessionManagementDisabled:YES];

这需要您手动管理会话

[MSAIApplicationInsights renewSessionWithId:@"4815162342"];

8.2 用户

通常，SDK会自动为您的应用中的每一位用户生成一个随机的匿名ID。或者，您也可以设置自己的用户ID或其他用户属性，这些属性将随后附加到所有遥测事件中。

  [[MSAIApplicationInsights sharedInstance] setUserWithConfigurationBlock:^(MSAIUser *user) {
    user.userId = @"your_user_id";
    user.accountId = @"[email protected]";
  }];

9. 设置自定义服务器端点

如果需要，您可以使用完整URL通过SDK配置不同的服务器端点。

[MSAIApplicationInsights setup]; //setup the SDK

[[MSAIApplicationInsights sharedInstance] setServerURL:@"https://YOURDOMAIN/path/subpath"];

[MSAIApplicationInsights start]; //start using the SDK

10. 文档

我们的文档可以在CocoaDocs上找到。

11. 贡献

我们期待您通过pull requests进行贡献。

开发环境

运行最新版OS X的Mac
从Mac App Store获取最新版本的Xcode
AppleDoc
Cocoapods

12. 联系方式

如果您有其他问题或遇到了无法通过以下步骤解决的问题，请随意在此处提交GitHub issue或通过以下链接与我们联系：[email protected]