HockeySDK-Mac 5.1.1

HockeySDK-Mac 5.1.1

×

许可证 MIT
发布最新发布2020年2月

由 Lukas Spieß、Microsoft、Clement Polet、Jae Lim、Alexander Chocron 维护。

HockeySDK-Mac 5.1.1

  • 由
  • Microsoft
此库已弃用，建议您查看 AppCenter。

Build StatusVersion Carthage compatible Slack Status

版本 5.0.0

注意：HockeySDK 4.0.0-alpha.1 的发布引入了一个错误，导致应用程序支持文件夹从 iCloud 和 iTunes 备份中排除。

如果您使用过受影响版本（4.0.0-alpha.2、版本 4.0.0、4.1.0-alpha.1、4.1.0-alpha.2 或版本 4.1.0-beta.1），请确保尽快升级到我们 SDK 的较新版本。

简介

HockeySDK-Mac 实现了在您的 Mac 应用程序中使用 HockeyApp 的支持。

以下功能目前被支持

  1. 收集崩溃报告：如果您的应用崩溃，则写入设备存储的崩溃日志将与苹果崩溃报告器相同的格式。如果用户重新启动应用，用户将被要求将崩溃报告提交给 HockeyApp。这对 beta 和实时应用都有效，即提交给 App Store 的应用！

  2. 用户指标：了解用户行为以提高您的应用。通过每日和月度活跃用户跟踪使用情况，监控受崩溃影响的用户，以及通过会话次数跟踪客户参与度。现在您可以在应用程序中跟踪自定义事件，了解用户操作，并在 HockeyApp 站点上查看聚合数据。

  3. 反馈：从您的应用程序内部收集用户反馈，并使用 HockeyApp 后端与他们直接沟通。

  4. 将分析添加到 Sparkle：如果您使用 Sparkle 提供应用程序更新（HockeyApp 也支持用于 beta 分发的 Sparkle 流），SDK 包含帮助程序来将一些分析数据添加到每个 Sparkle 请求。

此文档包含以下部分

  1. 要求
  2. 设置
  3. 高级设置
    1. 使用 CocoaPods 进行设置
    2. 崩溃报告
    3. 用户指标
    4. 反馈
    5. Sparkle
    6. 调试信息
  4. 文档
  5. 故障排除
  6. 贡献
    1. 行为准则
    2. 贡献者许可证
  7. 联系

1. 要求

  1. 我们假设您已经在 Xcode 中有一个项目，并且该项目已打开 Xcode 8 或更高版本。
  2. SDK 支持 OS X 10.9 及以上版本。

2. 设置

我们建议将我们的二进制文件集成到您的 Xcode 项目中，以为您 OS X 应用程序设置 HockeySDK。您还可以使用我们位于 HockeyApp for Mac 中的交互式 SDK 集成向导，该向导涵盖了以下步骤的所有内容。有关其他设置 SDK 的方法，请参阅 高级设置。

2.1 获取应用标识符

请参阅 "如何创建一个新的应用" 指南。这将为您提供用于初始化 SDK 的 HockeyApp 特定应用标识符。

2.2 下载 SDK

  1. 下载最新的 HockeySDK-Mac 框架，该框架以 zip 文件的形式提供。
  2. 解压文件，您将看到一个名为 HockeySDK-Mac 的文件夹。（请确保不要使用第三方解压工具！）

2.3 将 SDK 复制到 Finder 中的项目目录

根据我们的经验，第三方库通常位于一个子目录中（让我们将我们的子目录称为 Vendor），因此如果您没有使用库子目录组织项目，现在开始组织会是个好主意。为了继续我们的示例，在项目目录中创建一个名为 Vendor 的文件夹，并将解压后的 HockeySDK-Mac 文件夹移动到其中。

2.4 在 Xcode 中设置 SDK

  1. 我们建议使用 Xcode 的组功能创建一个类似于磁盘上我们的文件结构的第三方库组。例如，类似于 2.3 上述的文件结构，我们的项目有一个名为 Vendor 的组。

  2. 确保 项目导航器 是可见的（⌘+1）

  3. 将 HockeySDK.framework 从 Finder 中的窗口拖放到 Xcode 中的项目，并将其移动到 项目导航器 中希望的位置（例如，移动到名为 Vendor 的组）

  4. 将出现一个弹出窗口。选择 为任何添加的文件夹创建组 并为目标设置复选标记。然后单击 完成。

  5. 现在我们将确保框架被复制到您的应用程序包中

    • 单击 项目导航器 中的您的项目（⌘+1）。
    • 单击项目编辑器中的目标。
    • 单击 构建阶段 选项卡。
    • 在底部单击 添加构建阶段 按钮，并选择 添加复制文件。
    • 单击新构建阶段旁边的展开三角形。
    • 从目标列表中选择 框架。
    • 将 HockeySDK-Mac 从项目导航器左边的侧边栏拖放到新 复制文件 阶段的列表中。

  6. 由于 SDK 会在 Keychain 中存储与用户相关的输入以保护隐私，因此请确保为应用程序签名

2.5 修改代码

Objective-C

  1. 打开您的 AppDelegate.m 文件。
  2. 在文件顶部您的 import 语句下方添加以下行
@import HockeySDK;
  1. 搜索方法 applicationDidFinishLaunching:
  2. 添加以下行来设置和启动应用程序洞察 SDK
[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
// Do some additional configuration if needed here
[[BITHockeyManager sharedHockeyManager] startManager];

Swift

  1. 打开您的 AppDelegate.swift 文件。
  2. 在文件顶部您的 import 语句下方添加以下行
import HockeySDK
  1. 搜索方法 applicationWillFinishLaunching
  2. 添加以下行来设置和启动应用程序洞察 SDK
BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")
// Do some additional configuration if needed here
BITHockeyManager.shared().start()

注意： 如果是文档为基础的应用，请在 applicationDidFinishLaunching 的末尾调用 startManager，否则您可能丢失恢复、打开未命名文档等的苹果事件。

如果您的应用程序上次运行后已保存任何崩溃报告，则 startManager 将弹出一个对话框，允许用户提交它。完成提交或如果没有崩溃日志，它将回调用您的 appDelegate 并调用 showMainApplicationWindowForCrashManager:（如果实现，请见改进的启动崩溃处理）。

恭喜，现在您已经准备好使用HockeySDK了！

3. 高级设置

3.1 使用CocoaPods进行设置

CocoaPods 是Objective-C的依赖关系管理器，它能自动并简化在项目中使用如HockeySDK等第三方库的过程。要了解如何为您的项目设置CocoaPods，请访问官方CocoaPods网站。

Podfile

platform :osx, '10.9'
pod "HockeySDK-Mac"

3.2 崩溃报告

以下选项仅显示与崩溃报告功能交互和微调的某些可能性。有关更多信息，请参见文档中 BITCrashManager 类的完整文档。

3.2.1禁用崩溃报告

HockeySDK默认启用崩溃报告。崩溃将在下次应用程序启动时立即发送到服务器。

为了提供最好的崩溃报告，我们使用PLCrashReporter的1.2/提交356901d7f3ca3d46fbc8640f469304e2b755e461版本。

可以通过以下方式禁用此功能

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager] setDisableCrashManager: YES]; //disable crash reporting

[[BITHockeyManager sharedHockeyManager] startManager];

Swift

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")

BITHockeyManager.shared().isCrashManagerDisabled = true

BITHockeyManager.shared().start()

3.2.2自动发送崩溃报告

崩溃将在下次应用程序启动时发送。如果将 crashManagerStatus 设置为 BITCrashManagerStatusAutoSend，则崩溃将无需用户交互即可发送，否则将出现一个提示框，让用户选择是否要发送报告。

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager].crashManager setAutoSubmitCrashReport: YES];

[[BITHockeyManager sharedHockeyManager] startManager];

Swift

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")

BITHockeyManager.shared().crashManager.isAutoSubmitCrashReport = true

BITHockeyManager.shared().start()

SDK故意不在崩溃发生时立即发送报告，因为实现这种机制可能不安全，同时也不会造成更多危险，如设备的死锁。我们发现用户确实会再次启动应用程序，因为大多数人不知道发生了什么，并且您将得到迄今为止最多的报告。

启动时发送报告是通过异步方式完成的（非阻塞）。这是确保应用程序不会因iOS监视进程而被意外杀死的唯一安全方法，因为启动可能会花费太长时间，而当网络状况不佳或连接可能非常缓慢时，应用程序无法对任何用户输入做出反应。

3.2.3捕获更多异常

在Mac OS X上，有三种类型的崩溃不会报告给注册的 NSUncaughtExceptionHandler

  1. 自定义NSUncaughtExceptionHandler不会在 NSApplication 调用其所有代理方法之后开始工作！例如
- (void)applicationDidFinishLaunching:(NSNotification *)note {
...
[NSException raise:@"ExceptionAtStartup" format:@"This will not be recognized!"];
...
}
  1. 在 NSApplication 中默认的 NSUncaughtExceptionHandler 只会将异常记录到控制台并结束其处理。这导致在 NSApplication “作用域”中发生的异常不会在已注册的自定义 NSUncaughtExceptionHandler 中发生。例如
- (void)applicationDidFinishLaunching:(NSNotification *)note {
...
[self performSelector:@selector(delayedException) withObject:nil afterDelay:5];
...
}

- (void)delayedException {
NSArray *array = [NSArray array];
[array objectAtIndex:23];
}
  1. 在 IBAction 或其他 GUI 中发生的任何异常甚至都不会达到 NSApplication 默认未捕获异常处理程序。例如
- (IBAction)doExceptionCrash:(id)sender {
NSArray *array = [NSArray array];
[array objectAtIndex:23];
}

通常有两种解决方案。第一种方案是使用NSExceptionHandler类代替NSUncaughtExceptionHandler。但这种方法有一些缺点，具体细节可参考BITCrashReportExceptionApplication.h。

因此，我们提供了一个可选的NSApplication子类BITCrashExceptionApplication，用于处理2和3种情况。

安装

  • 打开应用程序的Info.plist文件。
  • 查找字段Principal class（主要类）。
  • 将NSApplication替换为BITCrashExceptionApplication。

或者，如果您有自己的NSApplication子类，请将其改为继承自BITCrashExceptionApplication。

3.2.4 添加附加数据

BITHockeyManagerDelegate协议提供了向崩溃报告添加额外数据的方法。

  1. 用户ID

Objective-C

- (NSString *)userIDForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;

Swift

可选公共函数 userID(for hockeyManager: BITHockeyManager!, componentManager: BITHockeyBaseManager!) -> String!

  1. 用户名

Objective-C

- (NSString *)userNameForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;

Swift

可选公共函数 userName(for hockeyManager: BITHockeyManager!, componentManager: BITHockeyBaseManager!) -> String!

  1. 用户邮箱

Objective-C

- (NSString *)userEmailForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;

Swift

可选公共函数 userEmail(for hockeyManager: BITHockeyManager!, componentManager: BITHockeyBaseManager!) -> String!

BITCrashManagerDelegate协议（它是自动包含在BITHockeyManagerDelegate中的）提供了向崩溃报告添加更多崩溃特定数据的方法

  1. 文本附件

Objective-C

-(NSString *)applicationLogForCrashManager:(BITCrashManager *)crashManager

Swift

可选公共函数 applicationLog(for crashManager: BITCrashManager!) -> String!

查看以下教程获取添加CocoaLumberjack日志数据的示例：如何在iOS或OS X上添加特定于应用程序的日志数据

  1. 二进制附件

Objective-C

-(BITHockeyAttachment *)attachmentForCrashManager:(BITCrashManager *)crashManager

Swift

可选公共函数 attachment(for crashManager: BITCrashManager!) -> BITHockeyAttachment!

确保实现协议

Objective-C

@interface YourAppDelegate () <BITHockeyManagerDelegate> {}

@end

Swift

class YourAppDelegate: NSObject, BITHockeyManagerDelegate {

}

并设置代理

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[[BITHockeyManager sharedHockeyManager] setDelegate: self];

[[BITHockeyManager sharedHockeyManager] startManager];

Swift

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")

BITHockeyManager.shared().delegate = self

BITHockeyManager.shared().start()

3.3 用户指标

HockeyApp会自动向您提供清晰、明智且富有信息量的指标，关于您的应用如何被使用以及由谁使用。

  • 会话：当包含的应用重新启动时（这指的是'冷启动'，即当应用之前未被载入内存时），或者当它在后台停留了20秒或更长的时间后重新变得活跃时，SDK会跟踪新的会话。
  • 用户：SDK通过创建一个随机UUID并安全存储在iOS密钥链中来匿名跟踪您的应用的用户。由于这个匿名ID存储在密钥链中，所以在重装应用程序后会持续存在。
  • 自定义事件：现在您可以在您的应用中跟踪自定义事件，了解用户的操作并在HockeyApp门户网站上查看汇总。

如果需要禁用自动收集匿名用户和会话统计数据，您在任何时候都可以关闭此功能

Objective-C

[BITHockeyManager sharedHockeyManager].disableMetricsManager = YES;

Swift

BITHockeyManager.shared().isMetricsManagerDisabled = true

3.3.1 自定义事件

通过跟踪自定义事件，现在您可以深入了解客户如何使用您的应用，了解他们的行为，在改进应用的同时回答重要的业务或用户体验问题。

  • 在开始跟踪事件之前，请思考您想要得到答案的问题。例如，您可能对业务、性能/质量或用户体验方面感兴趣。
  • 有意义地命名事件，并记住您将在HockeyApp网络门户网站上搜索事件时使用这些名称。请注意不要在事件跟踪过程中收集个人信息。

Objective-C

BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;

[metricsManager trackEventWithName:eventName]

Swift

let metricsManager = BITHockeyManager.shared().metricsManager

metricsManager.trackEvent(withName: eventName)

限制

  • 允许跟踪事件的字符为：[a-zA-Z0-9_. -]。如果您使用其他不允许的字符，事件将不会显示在 HockeyApp 网络门户中。
  • 目前每个应用程序每周对唯一事件名称的限制为 300 个。
  • 事件发生的次数没有限制。

3.3.2 将自定义属性和度量添加到自定义事件

可以将属性和/或度量添加到自定义事件。

  • 属性必须是字符串。
  • 测量值必须是数值类型。

Objective-C

BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;

NSDictionary *myProperties = @{@"Property 1" : @"Something",
@"Property 2" : @"Other thing",
@"Property 3" : @"Totally different thing"};
NSDictionary *myMeasurements = @{@"Measurement 1" : @1,
@"Measurement 2" : @2.34,
@"Measurement 3" : @2000000};

[metricsManager trackEventWithName:eventName properties:myProperties measurements:myMeasurements]

Swift

let myProperties = ["Property 1": "Something", "Property 2": "Other thing", "Property 3" : "Totally different thing."]
let myMeasurements = ["Measurement 1": 1, "Measurement 2": 2.3, "Measurement 3" : 30000]

let metricsManager = BITHockeyManager.shared().metricsManager
metricsManager.trackEvent(withName: eventName, properties: myProperties, measurements: myMeasurements)

3.4 反馈

BITFeedbackManager 允许您的用户通过应用程序和集成用户界面直接与您沟通。它提供了一个单线程的用户与运行您的应用程序的用户之间的讨论。如果将实际视图控制器集成到您的应用程序中，则此功能将启用。

您不应该创建自己的 BITFeedbackManager 实例，而应使用由 [BITHockeyManager sharedHockeyManager] 提供的实例。

Objective-C

[BITHockeyManager sharedHockeyManager].feedbackManager

Swift

BITHockeyManager.shared().feedbackManager

请查阅 BITFeedbackManager 类的文档了解更多如何利用此功能的信息。

3.5 Sparkle

3.5.1 为测试版分发设置

  1. 安装 Sparkle SDK：http://sparkle-project.org 截至 2016 年 1 月，Sparkle 不支持 Mac 闷盒（sandbox）。如果您需要此功能，请查看以下讨论 https://github.com/sparkle-project/Sparkle/issues/363

  2. 将 SUFeedURL 设置为 https://rink.hockeyapp.net/api/2/apps/<APP_IDENTIFIER> 并将 <APP_IDENTIFIER> 替换为用于初始化 HockeySDK 的相同值

  3. 创建应用程序捆绑包的 .zip 文件并将其上传到 HockeyApp。

3.5.2 向 Sparkle 配置添加分析数据

  1. 设置以下附加 Sparkle 属性
sparkleUpdater.sendsSystemProfile = YES;
  1. 添加以下 Sparkle 代理方法（不要忘记将 SUUpdater 绑定到您的 appDelegate！)
- (NSArray *)feedParametersForUpdater:(SUUpdater *)updater
sendingSystemProfile:(BOOL)sendingProfile {
return [[BITSystemProfile sharedSystemProfile] systemUsageData];
}
  1. 根据您的需要初始化使用跟踪。

一个示例场景是在应用程序启动或进入前台时以及当应用程序进入后台或被终止时

- (void)applicationWillFinishLaunching:(NSNotification *)aNotification
…      
NSNotificationCenter *dnc = [NSNotificationCenter defaultCenter];
BITSystemProfile *bsp = [BITSystemProfile sharedSystemProfile];
[dnc addObserver:bsp selector:@selector(startUsage) name:NSApplicationDidBecomeActiveNotification object:nil];
[dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillTerminateNotification object:nil];
[dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillResignActiveNotification object:nil];
…
};

3.6 调试信息

为了检查数据是否正确发送到 HockeyApp 以及在控制台中查看一些额外的 SDK 调试日志数据，请在调用 startManager 之前添加以下行

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];

[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;

[[BITHockeyManager sharedHockeyManager] startManager];

Swift

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")
BITHockeyManager.shared().logLevel = BITLogLevel.debug
BITHockeyManager.shared().start()

4. 文档

我们的文档可在中国 HockeyApp 上找到：HockeyApp。

5. 故障排除

  1. 程序启动时 dlyb 崩溃

确保应用程序的构建设置中将 LD_RUNPATH_SEARCH_PATHS 设置为 @executable_path/../Frameworks

  1. 带有 Xcode 调试器的启动时崩溃

确保没有激活的 所有异常 断点或在仅限于 Objective-C 的前提下并排除 C++。

  1. 功能没有按预期工作

启用控制台的调试输出以看到初始化 SDK 模块、发送和接收网络请求以及更多信息，请在调用 startManager 之前添加以下代码

[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;

6. 贡献

我们期待您通过拉取请求来贡献。

开发环境

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

6.1 行为准则

本项目采用了微软开源行为准则。更多信息请查看行为准则常见问题解答或通过联系邮箱。[email protected]提出任何额外的问题或评论。

6.2 贡献者许可协议

在提交拉取请求之前，您必须签署贡献者许可协议。要完成贡献者许可协议（CLA），您需要通过表格提交请求，并在收到包含文档链接的邮件后在线签署CLA。您只需要签署一次CLA即可涵盖对任何Microsoft OSS项目的提交。

7. 联系信息

如果您有进一步的问题或遇到无法通过此处任何步骤解决的问题，请在这里打开一个GitHub问题或通过联系邮箱。[email protected]联系。