TelemetryDeck 的 Swift SDK

此软件包允许您从 Swift 代码向 TelemetryDeck 发送信号。在 telemetrydeck.com 注册一个免费帐户。

安装 TelemetryDeck 最简单的方法是使用 Swift Package Manager，这是 Apple 内置于 Xcode 中的解决方案。在 Xcode 中，按File > Add Packages...，然后在出现的窗口中，在搜索字段中输入 https://github.com/TelemetryDeck/SwiftSDK。将 Dependency Rule 字段设置为 Up to Next Major Version，然后按 Add Package 按钮。Xcode 将下载它，然后您可以选择将“TelemetryDeck”库添加到应用程序的哪个目标（请注意，“TelemetryClient”是该库的旧名称）。

请参阅我们的详细设置指南以获取更多信息。

在应用程序启动时初始化 Telemetry Manager，以便它知道您的应用程序 ID（您可以从您的 TelemetryDeck 仪表板上的 Set Up App 下检索应用程序 ID）

let config = TelemetryDeck.Config(appID: "<YOUR-APP-ID>")
// optional: modify the config here
TelemetryDeck.initialize(config: config)

例如，如果您正在构建一个基于场景的应用程序，请在您的 App 的 init() 函数中进行初始化：

import SwiftUI
import TelemetryDeck

@main
struct TelemetryTestApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }

    init() {
        // Note: Do not add this code to `WindowGroup.onAppear`, which will be called
        //       *after* your window has been initialized, and might lead to our initialization
        //       occurring too late.
        let config = TelemetryDeck.Config(appID: "<YOUR-APP-ID>")
        TelemetryDeck.initialize(config: config)
    }
}

然后像这样发送信号：

TelemetryDeck.signal("App.launchedRegularly")

如果您的应用程序的构建配置设置为“Debug”，则发送的所有信号都将被标记为测试信号。在 Telemetry Viewer 应用程序中，激活 Test Mode 以查看这些信号。

如果您想手动控制测试模式是否处于活动状态，您可以设置 config.testMode 属性。

Telemetry Manager 将为您的用户创建一个特定于应用程序安装和设备的用户标识符。如果您有更好的用户标识符可用，例如电子邮件地址或用户名，您可以使用它来代替，方法是将其传递给 TelemetryDeck.Config（标识符将在发送之前进行哈希处理）。

config.defaultUser = "myuser@example.com"

您可以在 TelemetryDeck 已经初始化后更新配置。

您还可以为每个信号发送其他参数。

TelemetryDeck.signal("Database.updated", parameters: ["numberOfDatabaseEntries": "3831"])

对于每个信号，客户端都会发送您的用户 ID 的哈希值以及一个 *会话 ID*。这会在客户端初始化时自动生成，因此如果您什么都不做，每次从冷存储启动应用程序时，您都会获得一个新会话。

在 iOS、tvOS 和 watchOS 上，每当您的应用程序从后台返回，或者从冷存储启动时，会话标识符将自动更新。在其他平台上，每次应用程序启动时都会生成一个新的标识符。如果您需要更细粒度的会话支持，请在每次新会话开始时，将一个新的随机会话标识符写入 TelemetryDeck.Config 的 sessionID 属性。

默认情况下，用户标识符由 TelemetryDeck SDK 进行哈希处理，然后发送到 Ingestion API，在那里我们将向收到的标识符添加 salt 并再次对其进行哈希处理。

这足以满足大多数用例，但如果您希望具有额外的隐私意识，您可以在客户端添加自己的 salt。 TelemetryDeck SDK 将在哈希处理并将所有用户标识符发送给我们之前，将 salt 附加到它们。

如果您想使用自定义 salt，您可以通过将其传递给 TelemetryDeck.Config 来实现。

let config = TelemetryDeck.Config(appID: "<YOUR-APP-ID>", salt: "<A RANDOM STRING>")

我们客户中非常小的子集将希望使用自定义信号摄取服务器或自定义代理服务器。为此，您可以将自定义服务器的 URL 传递给 TelemetryDeck.Config

let config = TelemetryDeck.Config(appID: "<YOUR-APP-ID>", baseURL: "https://nom.telemetrydeck.com")

默认情况下，一些有助于监控 TelemetryDeck 的日志会打印到控制台。可以通过覆盖 config.logHandler 来自定义此行为。此结构接受最小允许的日志级别（将接受任何具有相同或更高日志级别的日志）和一个闭包。

这允许与其他日志记录解决方案（例如 swift-log）兼容，方法是提供您自己的闭包。

非常欢迎您在 TelemetryDeck 的 Swift SDK 上提交 PR。查看 SwiftClientTester 项目，它提供了一个工具，您可以使用它来处理该库并尝试新事物。

在进行新的发布时，运行 ./tag-release.sh MAJOR.MINOR.PATCH 以提升 SDK 中的版本字符串，创建一个新提交并相应地标记该提交，所有这些都在一步之内完成。