Support custom tracking when page views are tracked (#1124)

Author: waliid

Demo/Sources/Application/AppDelegate.swift

@@ -6,12 +6,14 @@
 
 import AVFAudio
 import Combine
+import os
 import PillarboxAnalytics
 import ShowTime
 import SRGDataProvider
 import UIKit
 
 final class AppDelegate: NSObject, UIApplicationDelegate {
+    private static let logger = Logger(category: "AppDelegate")
     private var cancellables = Set<AnyCancellable>()
 
     // swiftlint:disable:next discouraged_optional_collection
@@ -48,7 +50,7 @@ final class AppDelegate: NSObject, UIApplicationDelegate {
             sourceKey: .developmentSourceKey,
             appSiteName: "pillarbox-demo-apple"
         )
-        try? Analytics.shared.start(with: configuration, dataSource: self)
+        try? Analytics.shared.start(with: configuration, dataSource: self, delegate: self)
     }
 }
 
@@ -65,3 +67,13 @@ extension AppDelegate: AnalyticsDataSource {
         ])
     }
 }
+
+extension AppDelegate: AnalyticsDelegate {
+    func didTrackPageView(commandersAct commandersActPageView: CommandersActPageView) {
+        Self.logger.debug("[didTrackPageView] commandersAct: \(commandersActPageView.name)")
+    }
+
+    func didSendEvent(commandersAct commandersActEvent: CommandersActEvent) {
+        Self.logger.debug("[didSendEvent] commandersAct: \(commandersActEvent.name)")
+    }
+}

Demo/Sources/Showcase/ShowcaseView.swift

@@ -399,7 +399,7 @@ struct ShowcaseView: View {
             )
             cell(
                 title: "Video URN",
-                destination: .optInPlayer(media: URNMedia.onDemandVerticalVideo)
+                destination: .optInPlayer(media: URNMedia.onDemandHorizontalVideo)
             )
         }
         .sourceCode(of: OptInView.self)

Sources/Analytics/Analytics.docc/PillarboxAnalytics.md

@@ -56,6 +56,7 @@ Before submitting your app to production, validate it, especially after signific
 ### Configuration
 
 - ``AnalyticsDataSource``
+- ``AnalyticsDelegate``
 - ``CommandersActGlobals``
 - ``ComScoreGlobals``
 - ``ComScoreConsent``

Sources/Analytics/Analytics.swift

@@ -57,25 +57,28 @@ public class Analytics {
     private let commandersActService = CommandersActService()
 
     private weak var dataSource: AnalyticsDataSource?
+    private weak var delegate: AnalyticsDelegate?
 
     private init() {}
 
     /// Starts analytics with the specified configuration.
     ///
     /// - Parameters:
     ///   - configuration: The configuration to use.
-    ///   - dataSource: The data source to use.
+    ///   - dataSource: The object that acts as the data source of the analytics.
+    ///   - delegate: The object that acts as the delegate of the analytics.
     ///
     /// This method must be called from your `UIApplicationDelegate.application(_:didFinishLaunchingWithOptions:)`
     /// delegate method implementation, otherwise the behavior is undefined.
     ///
     /// The method throws if called more than once.
-    public func start(with configuration: Configuration, dataSource: AnalyticsDataSource? = nil) throws {
+    public func start(with configuration: Configuration, dataSource: AnalyticsDataSource? = nil, delegate: AnalyticsDelegate? = nil) throws {
         guard self.configuration == nil else {
             throw AnalyticsError.alreadyStarted
         }
         self.configuration = configuration
         self.dataSource = dataSource
+        self.delegate = delegate
 
         UIViewController.setupViewControllerTracking()
 
@@ -90,22 +93,22 @@ public class Analytics {
         commandersActService.trackPageView(
             commandersActPageView.merging(globals: dataSource?.commandersActGlobals)
         )
+        delegate?.didTrackPageView(commandersAct: commandersActPageView)
     }
 
     /// Sends an event.
     /// 
     /// - Parameter commandersActEvent: The Commanders Act event data.
     public func sendEvent(commandersAct commandersActEvent: CommandersActEvent) {
+        sendCommandersActEvent(commandersActEvent)
+        delegate?.didSendEvent(commandersAct: commandersActEvent)
+    }
+}
+
+extension Analytics {
+    func sendCommandersActEvent(_ commandersActEvent: CommandersActEvent) {
         commandersActService.sendEvent(
             commandersActEvent.merging(globals: dataSource?.commandersActGlobals)
         )
     }
 }
-
-public extension String {
-    /// The source key for apps in production.
-    static let productionSourceKey = "1b30366c-9e8d-4720-8b12-4165f468f9ae"
-
-    /// The source key for apps in development.
-    static let developmentSourceKey = "39ae8f94-595c-4ca4-81f7-fb7748bd3f04"
-}

Sources/Analytics/AnalyticsDelegate.swift

@@ -0,0 +1,11 @@
+//
+//  Copyright (c) SRG SSR. All rights reserved.
+//
+//  License information is available from the LICENSE file.
+//
+
+/// A delegate for analytics events.
+public protocol AnalyticsDelegate: AnyObject {
+    func didTrackPageView(commandersAct commandersActPageView: CommandersActPageView)
+    func didSendEvent(commandersAct commandersActEvent: CommandersActEvent)
+}

Sources/Analytics/CommandersAct/CommandersActEvent.swift

@@ -6,8 +6,11 @@
 
 /// A Commanders Act event.
 public struct CommandersActEvent {
-    let name: String
-    let labels: [String: String]
+    /// The event name.
+    public let name: String
+
+    /// Additional information associated with the event.
+    public let labels: [String: String]
 
     /// Creates a Commanders Act event.
     ///

Sources/Analytics/CommandersAct/CommandersActPageView.swift

@@ -6,10 +6,17 @@
 
 /// A Commanders Act page view.
 public struct CommandersActPageView {
-    let name: String
-    let type: String
-    let levels: [String]
-    let labels: [String: String]
+    /// The page name.
+    public let name: String
+
+    /// The page type (e.g., _Article_).
+    public let type: String
+
+    /// Additional information associated with the page view.
+    public let levels: [String]
+
+    /// The page levels.
+    public let labels: [String: String]
 
     /// Creates a Commanders Act page view.
     /// 

Sources/Analytics/CommandersAct/CommandersActTracker.swift

@@ -81,7 +81,7 @@ private extension CommandersActTracker {
         case (.none, _) where event != .play, (.eof, _) where event != .play:
             break
         default:
-            Analytics.shared.sendEvent(commandersAct: .init(
+            Analytics.shared.sendCommandersActEvent(.init(
                 name: event.rawValue,
                 labels: labels(from: properties)
             ))

Sources/Analytics/Extensions/String.swift

@@ -6,6 +6,14 @@
 
 import Foundation
 
+public extension String {
+    /// The source key for apps in production.
+    static let productionSourceKey = "1b30366c-9e8d-4720-8b12-4165f468f9ae"
+
+    /// The source key for apps in development.
+    static let developmentSourceKey = "39ae8f94-595c-4ca4-81f7-fb7748bd3f04"
+}
+
 extension String {
     var isBlank: Bool {
         trimmingCharacters(in: .whitespacesAndNewlines).isEmpty