[#701] Add foundation for analytics tracking

template/Modules/Analytics/Sources/Analytics.swift

@@ -0,0 +1,76 @@
+public final class Analytics: AnalyticsProtocol {
+
+    public static let shared: AnalyticsProtocol = Analytics()
+
+    private var trackers: [AnalyticsTracker] = []
+
+    private init() {}
+
+    // MARK: - Setup
+
+    public func configure(trackers: [AnalyticsTracker], additionalParameters: [String: Any]? = nil) {
+        self.trackers = trackers
+        trackers.forEach { $0.setUp(additionalParameters: additionalParameters) }
+    }
+
+    public func addTracker(_ tracker: AnalyticsTracker, additionalParameters: [String: Any]? = nil) {
+        trackers.append(tracker)
+        tracker.setUp(additionalParameters: additionalParameters)
+    }
+
+    // MARK: - Event Tracking
+
+    public func trackEvent(name: String, parameters: [String: Any]?) {
+        trackEvent(name: name, parameters: parameters, on: AnalyticsTrackerType.allCases)
+    }
+
+    public func trackEvent(name: String, parameters: [String: Any]?, on trackerTypes: [AnalyticsTrackerType]) {
+        let targetTrackers = trackers.filter { trackerTypes.contains($0.type) }
+        targetTrackers.forEach { $0.trackEvent(name: name, parameters: parameters) }
+    }
+
+    public func trackEvent(_ event: AnalyticsEvent) {
+        trackEvent(event, on: AnalyticsTrackerType.allCases)
+    }
+
+    public func trackEvent(_ event: AnalyticsEvent, on trackerTypes: [AnalyticsTrackerType]) {
+        trackEvent(name: event.name, parameters: event.parameters, on: trackerTypes)
+    }
+
+    // MARK: - Screen Tracking
+
+    public func trackScreen(name: String, screenClass: String?) {
+        trackScreen(name: name, screenClass: screenClass, on: AnalyticsTrackerType.allCases)
+    }
+
+    public func trackScreen(name: String, screenClass: String?, on trackerTypes: [AnalyticsTrackerType]) {
+        let targetTrackers = trackers.filter { trackerTypes.contains($0.type) }
+        targetTrackers.forEach { $0.trackScreen(name: name, screenClass: screenClass) }
+    }
+
+    // MARK: - User Properties
+
+    public func setUserProperty(key: String, value: String) {
+        setUserProperty(key: key, value: value, on: AnalyticsTrackerType.allCases)
+    }
+
+    public func setUserProperty(key: String, value: String, on trackerTypes: [AnalyticsTrackerType]) {
+        let targetTrackers = trackers.filter { trackerTypes.contains($0.type) }
+        targetTrackers.forEach { $0.setUserProperty(key: key, value: value) }
+    }
+
+    public func setUserId(_ userId: String?) {
+        setUserId(userId, on: AnalyticsTrackerType.allCases)
+    }
+
+    public func setUserId(_ userId: String?, on trackerTypes: [AnalyticsTrackerType]) {
+        let targetTrackers = trackers.filter { trackerTypes.contains($0.type) }
+        targetTrackers.forEach { $0.setUserId(userId) }
+    }
+
+    // MARK: - Utility
+
+    public func tracker(for type: AnalyticsTrackerType) -> AnalyticsTracker? {
+        trackers.first { $0.type == type }
+    }
+}

template/Modules/Analytics/Sources/AnalyticsEvent.swift

@@ -0,0 +1,5 @@
+public protocol AnalyticsEvent {
+
+    var name: String { get }
+    var parameters: [String: Any]? { get }
+}

template/Modules/Analytics/Sources/AnalyticsProtocol.swift

@@ -0,0 +1,51 @@
+public protocol AnalyticsProtocol {
+
+    // MARK: - Setup
+
+    func configure(trackers: [AnalyticsTracker], additionalParameters: [String: Any]?)
+    func addTracker(_ tracker: AnalyticsTracker, additionalParameters: [String: Any]?)
+
+    // MARK: - Event Tracking
+
+    func trackEvent(name: String, parameters: [String: Any]?)
+    func trackEvent(name: String, parameters: [String: Any]?, on trackerTypes: [AnalyticsTrackerType])
+    func trackEvent(_ event: AnalyticsEvent)
+    func trackEvent(_ event: AnalyticsEvent, on trackerTypes: [AnalyticsTrackerType])
+
+    // MARK: - Screen Tracking
+
+    func trackScreen(name: String, screenClass: String?)
+    func trackScreen(name: String, screenClass: String?, on trackerTypes: [AnalyticsTrackerType])
+
+    // MARK: - User Properties
+
+    func setUserProperty(key: String, value: String)
+    func setUserProperty(key: String, value: String, on trackerTypes: [AnalyticsTrackerType])
+    func setUserId(_ userId: String?)
+    func setUserId(_ userId: String?, on trackerTypes: [AnalyticsTrackerType])
+
+    // MARK: - Utility
+
+    func tracker(for type: AnalyticsTrackerType) -> AnalyticsTracker?
+}
+
+// MARK: - Default Parameters
+
+public extension AnalyticsProtocol {
+
+    func configure(trackers: [AnalyticsTracker]) {
+        configure(trackers: trackers, additionalParameters: nil)
+    }
+
+    func addTracker(_ tracker: AnalyticsTracker) {
+        addTracker(tracker, additionalParameters: nil)
+    }
+
+    func trackEvent(name: String) {
+        trackEvent(name: name, parameters: nil)
+    }
+
+    func trackScreen(name: String) {
+        trackScreen(name: name, screenClass: nil)
+    }
+}

template/Modules/Analytics/Sources/AnalyticsTracker.swift

@@ -0,0 +1,31 @@
+public protocol AnalyticsTracker {
+
+    var type: AnalyticsTrackerType { get }
+
+    func setUp(additionalParameters: [String: Any]?)
+    func trackEvent(name: String, parameters: [String: Any]?)
+    func trackScreen(name: String, screenClass: String?)
+    func setUserProperty(key: String, value: String)
+    func setUserId(_ userId: String?)
+}
+
+// MARK: - Extensions
+
+public extension AnalyticsTracker {
+
+    func setUp() {
+        setUp(additionalParameters: nil)
+    }
+
+    func trackEvent(name: String) {
+        trackEvent(name: name, parameters: nil)
+    }
+
+    func trackEvent(_ event: AnalyticsEvent) {
+        trackEvent(name: event.name, parameters: event.parameters)
+    }
+
+    func trackScreen(name: String) {
+        trackScreen(name: name, screenClass: nil)
+    }
+}

template/Modules/Analytics/Sources/AnalyticsTrackerType.swift

@@ -0,0 +1,4 @@
+public enum AnalyticsTrackerType: String, CaseIterable {
+
+    case console
+}

template/Modules/Analytics/Sources/ConsoleAnalyticsTracker.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+/// Console tracker that logs analytics events to the console for debugging
+public final class ConsoleAnalyticsTracker: AnalyticsTracker {
+
+    public let type: AnalyticsTrackerType
+    private let prefix: String
+
+    public init(type: AnalyticsTrackerType, logPrefix: String? = nil) {
+        self.type = type
+        self.prefix = logPrefix ?? "[\(type.rawValue.uppercased())]"
+    }
+
+    // MARK: - AnalyticsTracker Implementation
+
+    public func setUp(additionalParameters: [String: Any]?) {
+        let paramsString = additionalParameters?.description ?? "none"
+        print("\(prefix) SETUP - Additional parameters: \(paramsString)")
+    }
+
+    public func trackEvent(name: String, parameters: [String: Any]?) {
+        var message = "\(prefix) EVENT - \(name)"
+
+        if let parameters = parameters, !parameters.isEmpty {
+            let paramsString = parameters.map { "\($0.key): \($0.value)" }.joined(separator: ", ")
+            message += " | Parameters: {\(paramsString)}"
+        }
+
+        print(message)
+    }
+
+    public func trackScreen(name: String, screenClass: String?) {
+        var message = "\(prefix) SCREEN - \(name)"
+
+        if let screenClass = screenClass {
+            message += " | Class: \(screenClass)"
+        }
+
+        print(message)
+    }
+
+    public func setUserProperty(key: String, value: String) {
+        print("\(prefix) USER_PROPERTY - \(key): \(value)")
+    }
+
+    public func setUserId(_ userId: String?) {
+        let userIdString = userId ?? "null"
+        print("\(prefix) USER_ID - \(userIdString)")
+    }
+}

template/Modules/Analytics/Sources/Events/UserLoginEvent.swift

@@ -0,0 +1,20 @@
+/// Example analytics event for user login
+public struct UserLoginEvent: AnalyticsEvent {
+
+    public let name = "user_login"
+
+    public let loginMethod: String
+    public let isSuccessful: Bool
+
+    public init(loginMethod: String, isSuccessful: Bool = true) {
+        self.loginMethod = loginMethod
+        self.isSuccessful = isSuccessful
+    }
+
+    public var parameters: [String: Any]? {
+        return [
+            "login_method": loginMethod,
+            "is_successful": isSuccessful
+        ]
+    }
+}

template/Modules/Analytics/Sources/MockAnalyticsTracker.swift

@@ -0,0 +1,64 @@
+/// Mock tracker for testing purposes
+public final class MockAnalyticsTracker: AnalyticsTracker {
+
+    public let type: AnalyticsTrackerType
+
+    // MARK: - Tracked Data
+
+    public private(set) var isSetUp = false
+    public private(set) var setupParameters: [String: Any]?
+    public private(set) var trackedEvents: [(name: String, parameters: [String: Any]?)] = []
+    public private(set) var trackedScreens: [(name: String, screenClass: String?)] = []
+    public private(set) var userProperties: [String: String] = [:]
+    public private(set) var userId: String?
+
+    public init(type: AnalyticsTrackerType) {
+        self.type = type
+    }
+
+    // MARK: - AnalyticsTracker Implementation
+
+    public func setUp(additionalParameters: [String: Any]?) {
+        isSetUp = true
+        setupParameters = additionalParameters
+    }
+
+    public func trackEvent(name: String, parameters: [String: Any]?) {
+        trackedEvents.append((name: name, parameters: parameters))
+    }
+
+    public func trackScreen(name: String, screenClass: String?) {
+        trackedScreens.append((name: name, screenClass: screenClass))
+    }
+
+    public func setUserProperty(key: String, value: String) {
+        userProperties[key] = value
+    }
+
+    public func setUserId(_ userId: String?) {
+        self.userId = userId
+    }
+
+    // MARK: - Test Helpers
+
+    public func reset() {
+        isSetUp = false
+        setupParameters = nil
+        trackedEvents.removeAll()
+        trackedScreens.removeAll()
+        userProperties.removeAll()
+        userId = nil
+    }
+
+    public func hasTrackedEvent(name: String) -> Bool {
+        trackedEvents.contains { $0.name == name }
+    }
+
+    public func hasTrackedScreen(name: String) -> Bool {
+        trackedScreens.contains { $0.name == name }
+    }
+
+    public func eventCount(for name: String) -> Int {
+        trackedEvents.filter { $0.name == name }.count
+    }
+}

template/Modules/Analytics/Tests/Sources/Events/AnalyticsEventsSpec.swift

@@ -0,0 +1,23 @@
+import Testing
+@testable import Analytics
+
+@Suite("UserLoginEvent Tests")
+struct UserLoginEventTests {
+
+    @Test("Create event with correct parameters")
+    func createEventWithCorrectParameters() {
+        let event = UserLoginEvent(loginMethod: "email", isSuccessful: true)
+
+        #expect(event.name == "user_login")
+        #expect(event.parameters?["login_method"] as? String == "email")
+        #expect(event.parameters?["is_successful"] as? Bool == true)
+    }
+
+    @Test("Handle failed login")
+    func handleFailedLogin() {
+        let event = UserLoginEvent(loginMethod: "social", isSuccessful: false)
+
+        #expect(event.parameters?["is_successful"] as? Bool == false)
+        #expect(event.parameters?["login_method"] as? String == "social")
+    }
+}