SwiftEventTracker

SwiftEventTracker 是一个简单而灵活的 Swift 事件跟踪库。它使开发人员能够使用统一的、声明式的 API 跨多个分析服务提供商跟踪分析事件。使用 SwiftEventTracker，您可以轻松地与各种分析平台集成，而无需将您的代码与任何特定的 SDK 耦合。

入门指南

添加依赖

要在您的项目中使用 SwiftEventTracker，请将以下依赖添加到您的 Package.swift

.package(url: "https://github.com/hectr/swift-event-tracker", from: "2.0.0"),

然后，将 Tracker 添加到您的目标依赖项

.target(name: "YourAppTarget", dependencies: [
    .product(name: "Tracker", package: "swift-event-tracker")
]),

基本用法

导入库

首先导入 Tracker 模块

import Tracker

设置事件跟踪

1. 定义您的事件和屏幕

使用 Event 和 Screen 协议或提供的符合协议的结构体创建您的事件和屏幕。

let loginEvent = ParameterizedEvent(name: "login", parameters: ["method": "email"])
let homeScreen = NamedScreen(name: "HomeScreen")

2. 配置服务提供商

使用您要使用的服务提供商初始化 EventTracker。每个服务提供商必须符合 Service 协议。

let printProvider = PrintServiceProvider()

var tracker = EventTracker(serviceProviders: [printProvider])

3. 跟踪事件和屏幕

使用 trackEvent 和 trackScreen 方法来跟踪事件和屏幕视图。

tracker.trackEvent(loginEvent)
tracker.trackScreen(homeScreen)

高级用法

条件跟踪

给定条件

您可以根据自定义逻辑有条件地跟踪事件

tracker.trackEvent(loginEvent, given: { user.isLoggedIn })
标签

还可以使用 Tag 结构来实现条件跟踪。 请参阅 自定义事件和屏幕，属性和用户标识符 部分。

自定义事件和屏幕

事件

您可以通过遵循 Event 协议来创建自定义事件。 这允许您定义具有特定行为的事件，包括设置 excludedTags 和 requiredTags，这些标签控制是否应基于服务提供商支持的标签来跟踪事件。

这是一个例子

import Tracker

struct PurchaseEvent: Event {
    let name: String = "purchase"
    let parameters: [String: String]
    let date: Date
    
    var excludedTags: [Tag] {
        return [.debugging] // Exclude this event from providers tagged with `.crashReporting`
    }
    
    var requiredTags: [Tag] {
        return [.analytics] // Only track this event with providers tagged with `.analytics`
    }
    
    init(itemID: String, price: String) {
        self.parameters = ["item_id": itemID, "price": price]
        self.date = Date()
    }
}

// Usage
let purchaseEvent = PurchaseEvent(itemID: "12345", price: "19.99")
tracker.trackEvent(purchaseEvent)

此事件与任何服务提供商兼容。但只有内置支持它的提供商才会处理自定义的 date 属性。

屏幕

同样，您可以通过遵循 Screen 协议来定义自定义屏幕。 这对于使用自定义逻辑跟踪屏幕视图很有用，包括使用 excludedTags 和 requiredTags。

这是一个例子

import Tracker

struct ProductScreen: Screen {
    let name: String = "ProductScreen"
    let productID: String
    
    var excludedTags: [Tag] {
        return [.debugging] // Exclude this screen from providers tagged with `.debugging`
    }
    
    var requiredTags: [Tag] {
        return [.analytics] // Only track this screen with providers tagged with `.analytics`
    }
    
    init(productID: String) {
        self.productID = productID
    }
}

// Usage
let productScreen = ProductScreen(productID: "67890")
tracker.trackScreen(productScreen)

同样，只有内置支持此屏幕的服务提供商才会处理自定义的 productID 属性。

在 [./Sources/Tracker/events/vendor/](./Sources/Tracker/events/vendor/) 中查看更多示例。

属性和用户标识符

EventTracker 允许您定义可包含在所有跟踪事件中的属性和用户标识符。 这些属性可以全局或选择性地应用，具体取决于与每个服务提供商关联的标签。

设置属性

您可以设置将随每个事件一起发送的全局属性

// Global property applied to all providers
tracker.setProperty("user_type", value: "premium")

// Property applied only to providers tagged with `.crashReporting`
tracker.setProperty("app_version", value: "1.2.3", forTags: [.crashReporting])
重置属性

如果需要，您可以全局或针对特定标签重置属性

// Reset properties only for providers tagged with `.debugging`
tracker.resetProperties(forTags: [.debugging])

// Reset all properties for all providers
tracker.resetProperties()
设置用户标识符

用户标识符是可以全局或针对特定服务提供商设置的另一个关键属性

// Global user identifier applied to all providers
tracker.setUserId("user_12345")

// User identifier applied only to providers tagged with `.analytics`
tracker.setUserId("user_12345", forTags: [.analytics])
重置用户标识符

与属性类似，用户标识符也可以全局或选择性地重置

// Reset user identifier for all providers
tracker.resetUserId()

// Reset user identifier only for providers tagged with `.logging` and `.crashReporting`
tracker.resetUserId(forTags: [.logging, .crashReporting])

在运行时切换服务提供商

您可以动态更新服务提供商列表

let appCenterProvider = AppCenterAnalyticsServiceProvider(adapter: Analytics.self) 
let adjustProvider = AdjustServiceProvider(adapter: Adjust.self)
let taplyticsProvider = TaplyticsServiceProvider(adapter: Taplytics.self)
let instabugProvider = InstabugServiceAdapter(adapter: Instabug.self)

tracker.setServiceProviders([appCenterProvider, adjustProvider, taplyticsProvider, instabugProvider])

添加自定义服务提供商

SwiftEventTracker 支持各种分析服务提供商，包括 Firebase、Amplitude、Mixpanel 等。 要添加对新提供商的支持，您需要实现 Service 协议并提供符合相应适配器协议的适配器。

这是一个简化的例子

import Tracker

class CustomAnalyticsProvider: Service, AbstractProvider {
    let supportedTags: [Tag] = [.analytics]

    func trackEvent(_ event: Event) {
        // Implement custom event tracking logic here
    }
}

为了进一步自定义，您可以实现方法 trackScreen(_:), setUserId(_:), resetUserId(), setProperty(_:value:), resetProperties(), 和 disableTracking(_:).

可用的服务提供商

SwiftEventTracker 附带多个分析提供商

实现适配器

每个提供商的适配器实现留给使用者。 以下是 Firebase 适配器的示例

import FirebaseAnalytics
import Tracker

extension Analytics: FirebaseAnalyticsServiceAdapter {}

// Usage
let firebaseProvider = FirebaseAnalyticsServiceProvider(adapter: Analytics.self)
var tracker = EventTracker(serviceProviders: [firebaseProvider])

这允许 SwiftEventTracker 利用 Firebase 的功能，而无需直接依赖其 SDK。 请注意，您的应用程序仍然需要处理 Firebase 配置和初始化。

您可以在示例包中找到其余支持服务的示例。

许可证

SwiftEventTracker 在 MIT 许可证下可用。 有关更多信息，请参见 LICENSE 文件。

贡献

欢迎贡献！ 如果您有想法、建议或想为代码库做出贡献，请随时提出问题或提交拉取请求。

替代方案