HockeySDK-tvOS 5.1.0

HockeySDK-tvOS 5.1.0

×

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

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

HockeySDK-tvOS 5.1.0

  • 由
  • 微软
此库已废弃，建议您查看 AppCenter。

Build Status Version Slack Status

HockeySDK-tvOS

版本 5.0.0

简介

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

目前支持以下功能：

  1. 收集崩溃报告：如果您的应用崩溃，则会将格式与 Apple 崩溃报告相同的崩溃日志写入设备存储。如果用户再次启动应用，则会要求用户将崩溃报告提交给 HockeyApp。这适用于测试版和正式版应用，即提交到 App Store 的应用。

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

  3. 更新通知：应用将检查是否存在适用于您的 Ad-Hoc 或企业构建的新版本。如果存在，它将显示包含最新版本信息的警报视图。

  4. 认证：识别和认证 Ad-Hoc 或企业构建的用户

本文档包含以下章节

  1. 要求
  2. 配置
  3. 高级配置
  4. 使用 CocoaPods 进行配置
  5. 崩溃报告
  6. 用户度量
  7. 应用内更新（beta 和企业版仅限）
  8. 调试信息
  9. 文档
  10. 故障排除
  11. 贡献
  12. 开发环境
  13. 行为准则
  14. 贡献者许可
  15. 联系信息

1. 要求

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

[注意]请注意，tvOS 需要 Bitcode。

2. 配置

我们建议将我们的二进制文件集成到您的 Xcode 项目中以设置针对 tvOS 应用的 HockeySDK。

2.1 获取应用程序标识符

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

2.2 下载SDK

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

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

将解压后的HockeySDK-tvOS文件夹移动到您的项目目录。根据我们的经验，大多数项目都会专门为第三方库设立一个目录。这些说明假定您的项目具有此类目录，并且它被命名为Vendor。

2.4 在Xcode中设置SDK

  1. 我们建议在Xcode项目中为第三方库创建一个组，类似于磁盘上文件的结构。在这种情况下，该组将被称为Vendor，与目录相匹配。
  2. 确保项目导航器是可见的（⌘+1）
  3. 从Finder中的窗口（这将是Vendor目录）拖放HockeySDK.framework到Xcode中的项目，并将其移动到项目导航器中希望的位置（例如，到名为Vendor的组中）
  4. 将出现一个对话框。选择为任何添加的文件夹创建组，并勾选目标框。如果您有多个目标，请确保选择您的tvOS目标。现在点击完成。

2.5 将SDK集成到您的代码中

Objective-C

  1. 打开包含您的应用程序代理的文件（默认项目中的AppDelegate.m）。
  2. 在您自己的import语句下方添加以下行
@import HockeySDK;
  1. 在方法application:didFinishLaunchingWithOptions:中，添加以下行以初始化并启动HockeySDK
[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
// Do additional configuration if needed here
[[BITHockeyManager sharedHockeyManager] startManager];
[[BITHockeyManager sharedHockeyManager].authenticator authenticateInstallation];

Swift 3

  1. 打开包含您的应用程序代理的文件（默认项目中的AppDelegate.swift）。
  2. 在您自己的import语句下方添加以下行
import HockeySDK
  1. 在方法application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool中，添加以下行以初始化并启动HockeySDK
BITHockeyManager.shared().configure(withIdentifier: appId)
BITHockeyManager.shared().start()
BITHockeyManager.shared().authenticator.authenticateInstallation() // This line is obsolete in the crash only builds

注意：SDK已优化以便尽可能延迟初始化，同时确保启动时可以捕获崩溃。每个模块以最多几秒钟的延迟执行其他代码。这确保了您的启动方法将尽可能地快速执行，并且SDK不会阻止启动过程（这将是糟糕的用户体验，并可能导致系统看门狗进程杀死您的应用）。

2.6 Bitcode

请务必阅读我们知识库中的关于Bitcode的文章，以确保您的崩溃能够正确符号化。

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

3. 高级设置

3.1 使用CocoaPods设置

CocoaPods是Objective-C的依赖项管理器，它自动简化了在项目中使用诸如HockeySDK之类的第三方库的过程。有关如何为您的项目设置CocoaPods的说明，请访问官方CocoaPods网站。

Podfile

platform :tvos, '10.0'
pod 'HockeySDK-tvOS'

3.2 崩溃报告功能

由于当前发布的版本是beta版本，因此崩溃报告当前具有有限的配置和微调选项。

3.2.1 禁用崩溃报告

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

为了提供最佳崩溃报告，我们在版本b1b94c016f9661af13bdf6295c3cd55cc7d6a56f下使用Plausible Labs' PLCrashReporter的一个自定义分支。

以下代码可以用来禁用此功能

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
[[BITHockeyManager sharedHockeyManager] setDisableCrashManager:YES]; //disable crash reporting
[[BITHockeyManager sharedHockeyManager] startManager];

Swift 3

BITHockeyManager.shared().configureWithIdentifier("APP_IDENTIFIER")
BITHockeyManager.shared().isCrashManagerDisabled = true
BITHockeyManager.shared().startManager()

3.2.2 崩溃报告是如何发送到HockeyApp的？

崩溃将在应用启动时发送，无需用户任何交互。

SDK避免在崩溃时发送报告，因为这无法安全地实现。特别是，在没有造成设备资源严重消耗的情况下，无法以异步安全的方式执行网络访问，任何错误都可能导致双重故障或死锁，从而彻底丢失崩溃报告。我们发现用户确实会重新启动应用，因为大多数人不知道发生了什么，您将会收到绝大多数的崩溃报告。

在启动时异步发送挂起的崩溃报道，使用NSURLSession。这避免了与缓慢启动有关的问题，并且对网络连接不良具有弹性。

3.2.4 添加附加数据

BITHockeyManagerDelegate协议提供了将附加数据添加到崩溃报告的方法

  1. UserID: - (NSString *)userIDForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;
  2. UserName: - (NSString *)userNameForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;
  3. UserEmail: - (NSString *)userEmailForHockeyManager:(BITHockeyManager *)hockeyManager componentManager:(BITHockeyBaseManager *)componentManager;

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

  1. 文本附件: -(NSString *)applicationLogForCrashManager:(BITCrashManager *)crashManager

查看以下教程以了解如何添加CocoaLumberjack日志数据的示例： 如何在iOS或OS X中添加特定于应用日志数据 2. 字节附件: -(BITHockeyAttachment *)attachmentForCrashManager:(BITCrashManager *)crashManager

确保实现该协议

Objective-C

@interface YourAppDelegate () <BITHockeyManagerDelegate> {}

@end

Swift 3

class ViewController: UIViewController, BITHockeyManagerDelegate { .... }

并设置代理

Objective-C

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

[[BITHockeyManager sharedHockeyManager] setDelegate: self];

[[BITHockeyManager sharedHockeyManager] startManager];

Swift 3

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")
BITHockeyManager.shared().delegate = self
BITHockeyManager.shared().start()

3.3 用户指标

HockeyApp会自动提供有关你的应用如何被使用以及由谁使用的卑切、易理解且信息丰富的指标。

  • 会话：SDK会在包含的应用重启或每次它在后台超过20秒后再变为活跃时追踪新的会话（这指的是“冷启动”，即应用在被启动之前尚未在内存中）。
  • 用户：通过创建一个随机UUID并将其然后安全地存储在tvOS密钥链中，SDK匿名跟踪应用的用户。因为这个匿名ID存储在密钥链中，所以它可以跨重新安装持久化。
  • 自定义事件：从HockeySDK 4.1.0开始，你现在可以跟踪应用中的自定义事件，了解用户行为并查看HockeyApp门户上的聚合数据。

如果你想要禁用匿名用户和会话统计信息的自动收集，你可以随时关闭此功能

Objective-C

[BITHockeyManager sharedHockeyManager].disableMetricsManager = YES;

Swift 3

BITHockeyManager.shared().isMetricsManagerDisabled = true

3.3.1 自定义事件

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

  • 在开始跟踪事件之前，请思考您想要得到答案的问题。例如，您可能对业务、性能/质量或用户体验方面感兴趣。
  • 合理命名您的自定义事件，并在使用HockeyApp网页门户中的事件搜索时记住这些名称。不要收集个人数据作为事件跟踪的一部分。

Objective-C

BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;
[metricsManager trackEventWithName:eventName]

Swift 3

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 3

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, myMeasurements: measurements)

3.4 应用内部更新通知（测试版 & 企业版仅限）

以下选项仅显示在使用测试或企业配置文件提供时与更新特性互动和微调的一些可能性。欲了解更多信息，请查看我们的文档中关于BITUpdateManager类的完整文档。

此功能通过弹出窗口显示更新和版本信息。

默认情况下，当运行在App Store构建时，此模块会自动禁用！

可以手动禁用应用内部更新通知，方法如下

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
[[BITHockeyManager sharedHockeyManager] setDisableUpdateManager: YES]; //disable auto updating
[[BITHockeyManager sharedHockeyManager] startManager];

Swift 3

BITHockeyManager.shared().configure(withIdentifier: "APP_IDENTIFIER")
BITHockeyManager.shared().isUpdateManagerDisabled = true //disable auto updating
BITHockeyManager.shared().start()

3.5 调试信息

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

Objective-C

[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;
[[BITHockeyManager sharedHockeyManager] startManager];

Swift 3

BITHockeyManager.shared().configure(withIdentifier: appId)
BITHockeyManager.shared().logLevel = .verbose
BITHockeyManager.shared().start()

4. 文档

我们的文档可以在HockeyApp找到。

5. 故障排除

  1. iTunes Connect被拒绝

请确保以下文件没有复制到您的应用束中。这可以通过检查Xcode项目中您的应用目标在“构建阶段”标签下的“Copy Bundle Resources”项或通过在构建后检查最终的.app束来完成

  • HockeySDK.framework（除非您已构建SDK的动态框架版本-如果您不知道这意味着什么，您不需要担心这项）
  • de.bitstadium.HockeySDK-tvOS-5.0.0.docset
  1. 功能未按预期工作

启用控制台调试输出以查看SDK在初始化模块、发送和接收网络请求等时的额外信息，方法是在调用startManager之前添加以下代码

`[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;`

6. 贡献

我们期待通过pull request方式收到您的贡献。

6.1 开发环境

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

6.2 行为守则

本项目采用了微软开源行为守则。了解更多信息，请参阅行为守则常见问题，或联系[email protected]提出任何额外问题或意见。

6.3 贡献者许可协议

在提交拉取请求之前，您必须签署一个贡献者许可协议。要完成贡献者许可协议（CLA），您必须通过此表格提交请求，然后在收到含有文档链接的电子邮件后，在电子邮件中电子签署CLA。对于任何项目，一旦签署CLA，就覆盖了所有提交给所有微软开源项目的贡献，除非另有说明。

7. 联系

如果您还有其他问题或遇到无法解决的问题，请随时创建一个GitHub问题，或在[email protected]联系我们。