iOS 和 iPadOS 的 Trap 库

该库可以收集各种设备和用户数据,并将其转发到指定的端点。此版本捆绑了以下数据收集器:

如何使用

您可以查看示例应用程序以获得一个可运行的示例

import Trap
import SwiftUI

@main
struct ExampleApp: App {
    let trapManager: TrapManager

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }

    public init() {
        /// Create a new configuration instance.
        var config = TrapConfig()

        /// Change what you need to change
        config.reporter.interval = .seconds(3)

        /// Set either a websocket endpoint...
        config.reporter.url = "wss://example.com/api/ws"

        /// ...or a HTTP POST endpont.
        config.reporter.url = "https://example.com/api/post"

        trapManager = TrapManager(withConfig: config)

        // Run all default collectors...
        trapManager.runAll()

        // ...or use it one collector at a time
        let collector = TrapPreciseLocationCollector(withConfig: config)

        /// Check if the build-time conditions are ready for the collector
        if collector.checkConfiguration() {
            /// Check if the runtime permissions are given.
            if !collector.checkPermission() {
                /// Request the permission if you need to
                collector.requestPermission { [self] in trapManager.run(collector: collector) }
            } else {
                /// ...or run the collector immediately.
                trapManager.run(collector: collector)
            }
        }
    }
}

提供自定义元数据

您可以添加和删除自定义元数据(字符串键值对),这些元数据将作为元数据事件的一部分定期发送到服务器。

添加元数据

trapManager.addCustomMetadata(key: "some-key", value: "some-value")

删除元数据

trapManager.removeCustomMetadata(key: "some-key")

发送带有自定义数据的事件

您还可以向事件流添加自定义事件。 该事件可以包含简单类型(字符串、数字、布尔值)和复杂类型(这些类型的字典和数组)。

trapManager.addCustomEvent(custom: DataType.dict([
    "some-key": DataType.string("some-data"),
    "numeric-data-key": DataType.int(2),
    "boolean-data-key": DataType.bool(false)
]))

权限

许多可用的数据收集器需要应用包记录 (Info.plist) 和/或授权。 其中一些需要 Apple 的特殊批准。 以下是每个收集器的详细信息:

加速度计、重力、陀螺仪、磁力计

唯一的要求是定义并填写包记录“NSMotionUsageDescription”。

低功耗蓝牙

唯一的要求是定义并填写包记录“NSBluetoothAlwaysUsageDescription”。 需要用户在运行时授予权限。

大致和精确位置

需要设置以下包记录

需要用户在运行时授予权限。

WiFi

完整操作需要以下授权

只有在 Apple 批准您的应用程序后,才能获得 HotspotHelper 授权(可在 Apple HotspotHelper Request 获取)。

开发说明

该库的核心是 TrapManager 类。 它管理各个收集器,这些收集器对最终开发人员可用。 另一方面是数据帧传输系统,它是一个可配置间隔的无休止重复的任务。 报告任务将数据包发送到指定的端点。 这两个方面之间的连接是一个内存数据存储,它通过自定义环形队列实现。

实现的目的是低且可预测的平稳资源使用。 因此,在关键的 UI 路径上,我们试图尽可能避免分配和处理。 处理部分主要在后台线程上进行。 为此,我们使用 OperationQueues。

法律警告

此库收集的许多数据类型都能够识别单个用户,因此集成应用程序可能会受到 GDPR 和/或 CCPA 的影响。 您全权负责通过此库收集和处理的数据。

许可证

在 MIT 许可证下获得许可。