SimpleAnalytics

您可能希望通过分析报告来深入了解您的 iOS 或 Mac 应用，但又不想承担未知的风险，或某些第三方分析包可能存在的侵入式过度共享行为。SimpleAnalytics 是一种替代方案，它将所有关于发送什么以及发送给谁的控制权都掌握在您手中。

SimpleAnalytics 允许您捕获应用中的用户行为，并将它们提交到您控制或有权访问的服务器。配套项目 SimpleAnalytics Reader（请参阅下面的查看收集的数据部分）让您可以在 Macintosh 桌面应用程序中访问您收集的数据。

请参阅 SimpleAnalyticsDemo 项目，了解在 Xcode 项目中使用它的一个基本示例。

在 2023 年 7 月，苹果宣布，从 2023 年秋季开始，它将要求开发者报告对“所需原因”API 的使用，包括 UserDefaults。苹果开发者页面

由于 Simple Analytics 的原始版本调用了 UserDefaults 来持久化一个在应用启动时对设备来说是唯一的标识字符串，您需要在未来的应用版本中包含该用法。

在 Simple Analytics 的 3.0 及更高版本中，用于初始化分析报告会话的 API 发生了变化。它的 setEndpoint... 方法现在需要传入一个设备标识符字符串。UserDefaults 的所有使用都已从框架中移除。

如果您是从早期版本的 Simple Analytics 升级，则需要更新您的应用程序代码中对 setEndpoint 方法的调用。此外，如果您想在分析报告中包含设备标识符，您需要设计自己的方法来持久化该标识符。随附的演示项目中的 AnalyticsManager 文件中使用了一种可能符合苹果新规则的方法。

SimpleAnalytics 以 Swift 包的形式分发，您可以使用 Xcode 11.0 及更高版本中内置的工具将其加载到 Xcode 项目中。

在项目配置面板的 Swift Packages 部分，包含一个 SimpleAnalytics 的依赖项，URL 为

https://github.com/dennisbirch/simple-analytics

如果 SimpleAnalytics 没有自动添加到您的目标的 Frameworks 列表，请务必手动添加。

将 SimpleAnalytics 添加到您的 Xcode 项目后，您就可以开始添加代码来捕获应用使用数据了。

第一步是配置应用程序以指向您设置的用于处理 SimpleAnalytics 请求的 Web 服务。

• 请参阅该软件包中包含的任何示例应用程序，了解应用程序配置的实现。
• 请参阅下面的文档，了解有关配置应用程序所需的详细信息，以及 Web 应用程序期望接收和应返回的内容。
• 请参阅 analytics.php 文件，了解后端 Web 应用程序的示例。

您可以通过导入 SimpleAnalytics 模块，然后使用两个可用的静态方法之一来记录观察结果，从而从应用程序代码的任何位置调用 SimpleAnalytics 包。如下面的详细描述，有两种方法：1) 记录包含可选附加详细信息的动作；以及 2) 在发生动作时递增计数器。

在代码中可能看起来像这样

AppAnalytics.addItem("Logged out")
AppAnalytics.addItem("Logged in", params: ["method" : loginMethod])
AppAnalytics.addItem("Changed 'Timeout' settings", params: ["minutes" : String(newTimeout),
                                                            "apply to" : String(describing: applyToOptions)])

AppAnalytics.countItem("Foregrounded app")
AppAnalytics.countItem("Set new password")

请参阅任何示例应用程序，了解其他用法示例以及将对 SimpleAnalytics 模块的调用集中在一个控制器类型中的方法。

有四个不同的 Xcode 项目演示了在不同环境中使用 SimpleAnalytics 包，每个项目都在不同的文件夹中

• SimpleAnalyticsDemo - 使用 SwiftUI 实现，包含 macOS 和 iOS 目标
• SimpleAnalyticsDemo-AppKit - 使用 Swift 实现，适用于 macOS，使用 AppKit
• SimpleAnalyticsDemo-UIKit - 使用 Swift 实现，适用于 iOS，使用 UIKit
• SimpleAnalyticsDemo-ObjC - 使用 Objective-C 实现，适用于 macOS，使用 AppKit

要运行它们中的任何一个，只需打开文件夹中的 xcodeproj 文件即可。

有一个配套的开源项目 SimpleAnalytics Reader 可用于查看您的应用程序正在收集的有关其使用情况的数据。您可以在 https://www.github.com/dennisbirch/simple-analytics-reader 找到它。它包含 macOS 应用程序的源代码和一个后端 Web 应用程序，您可以按原样运行，或者用于启发您编写自己的后端。该界面提供了不同的查询和查看数据的方式，以满足您的需求。

SimpleAnalytics 包需要一个配置步骤才能完全实现，并提供其他几个配置选项。

为了将您的应用程序的分析数据从用户的设备提交到您可以访问的 Web 服务，您需要设置 Web 服务的端点。Web 服务可以是任何可以处理 JSON 负载的 Web 应用程序。

2.0 及更高版本中的新增功能：在 iOS 上，您还需要提供对共享应用程序实例的引用。SimpleAnalytics 使用它来请求和释放后台任务，以便将数据提交到您的 Web 服务。

调用 AppAnalytics.setEndpoint(_:, deviceID:, submissionCompletionCallback:) 方法。

参数

urlString：您的 Web 服务 URL 的字符串。

deviceID：如果希望在分析报告中跟踪设备，则可以使用字符串标识设备。请参阅上面“重要 v3.0 注意事项”部分中对此参数的讨论。

submissionCompletionCallback：一个可选的完成回调，没有参数，也没有返回值，用于向您的 macOS 应用程序发出提交完成的信号。这对于在分析提交完成之后实现终止应用程序的策略非常有用。

#####要在 iOS 上设置端点和共享应用程序：调用 AppAnalytics.setEndpoint(_:, deviceID:, sharedApp:) 方法。

参数

urlString：您的 Web 服务 URL 的字符串。

deviceID：如果希望在分析报告中跟踪设备，则可以使用字符串标识设备。请参阅上面“重要 v3.0 注意事项”部分中对此参数的讨论。

sharedApp：将 UIApplication.shared 属性传递给此参数。

此调用应在您的应用程序生命周期中尽早进行。

为了帮助区分数据条目，SimpleAnalytics 为每个条目都包含一个平台字段。该框架自动为这些平台分配值 iOS 和 macOS 以及 iOS 的设备类型。但是，如果您的应用程序在混合环境中运行（例如，在 Mac 上运行的 iOS 应用程序），您可以使用 AppAnalytics.setPlatform(_:) 方法覆盖该分配。

参数

platformName：包含平台名称的字符串。

当数据项的总计数达到最大计数时，SimpleAnalytics 会自动尝试提交其内容。默认最大值为 100，但您可以更改它以适应您的应用程序的需求。要更改最大计数值，请调用 AppAnalytics.setMaxItemCount(_:) 方法。

参数

count：Int 定义在尝试将它们提交到您的服务器之前要累积的项目基本最大数量。

当提交尝试失败时，SimpleAnalytics 会恢复它试图提交的项目，以便后续重新提交。它还会增加最大计数值，以便在后续新事件触发另一次提交尝试之前添加延迟。此失败增量的默认值为 20。您可以通过调用 AppAnalytics.setSubmitFailureIncrement(_:) 方法来更改它。

参数

increment：Int 定义在再次尝试提交条目之前要添加到最大项目计数的数量。

SimpleAnalytics 在进入后台时会自动尝试提交其数据。您可以通过调用 AppAnalytics.overrideSubmitAtDismiss(: ) 方法来覆盖该行为。

参数

shouldSubmit：Bool。传入 false 以关闭自动提交，或传入 true 以重新打开该行为。

SimpleAnalytics 提供了两种记录分析数据的方法。

分析项目：此选项允许您为项目定义一个名称，并且可以选择包含一个 [String:String] 附加参数字典。您有责任确保不包含私人的用户信息。

计数器：此选项允许您命名要记录的动作或行为，并在每次重复时递增计数器。

要添加分析项目，请调用 AppAnalytics.addItem(_: parameters:)。

参数

description：描述动作或用户交互的字符串

params：一个可选的 [String:String] 附加详细信息字典，用于记录（例如，某些应用程序状态观察）以进行更精细的分析

要添加或递增计数器，请调用 AppAnalytics.countItem(_:)。请注意，添加新计数器会向总计数添加一个项目。递增现有计数器不会添加到项目计数。由于这个原因以及计数器不包含其他详细信息并且不接收时间戳的事实，它们比分析项目更轻量级。

参数

description：描述要计数的项目的字符串。添加一个项目并将其设置为值 1，或递增 1。

SimpleAnalytics 将您添加的所有分析条目保存在 AppAnalytics 共享实例中的两个数组中，直到它尝试将数据提交到您的服务器。默认情况下，SimpleAnalytics 会在总共累积了 100 个项目后以及托管它的应用程序发送到后台时尝试提交。

如果提交尝试失败，则从 AppAnalytics 数组中删除的项目将恢复到下次尝试。

如上面配置部分中所讨论的，您可以配置一些值来影响 AppAnalytics 何时提交数据。

您可以通过调用 AppAnalytics.submitNow() 方法随时触发提交尝试。

确定是否强制提交尝试时，了解 AppAnalytics 数据数组的总计数可能会有所帮助。为此，请访问 AppAnalytics.itemCount 公共属性。

AppAnalytics 以 JSON 负载的形式提交其数据，格式如下

您的 Web 应用程序应以以下 JSON 格式响应有效负载的处理：

注意： 如果未能发送格式正确的响应，SimpleAnalytics 将重新发送相同的项目。

有关如何在 Web 服务器上处理传入的 JSON 有效负载并发送响应的示例，请参见软件包中包含的 Analytics.php 文件。

SimpleAnalytics 提供了将收集的数据持久化到磁盘以及从该持久化存储恢复数据的方法。默认情况下，它不会调用这两个方法中的任何一个，以避免负责重复条目。 如果您想管理数据的保存和恢复时间，可以使用这些方法。

要持久化分析数据，请调用 AppAnalytics.persistContents() 方法。

要恢复保存的内容（例如，在应用程序启动时），请调用 AppAnalytics.restorePersistenceContents() 方法。

欢迎贡献。 要提出改进建议，请提交 pull request。