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

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,9 @@ extension AppDelegate: AnalyticsDataSource {
         ])
     }
 }
+
+extension AppDelegate: AnalyticsDelegate {
+    func didTrackPageView(commandersAct commandersActPageView: CommandersActPageView) {
+        Self.logger.debug("[didTrackPageView] commandersActPageView: \(commandersActPageView.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,6 +93,7 @@ public class Analytics {
         commandersActService.trackPageView(
             commandersActPageView.merging(globals: dataSource?.commandersActGlobals)
         )
+        delegate?.didTrackPageView(commandersAct: commandersActPageView)
     }
 
     /// Sends an event.

Sources/Analytics/AnalyticsDelegate.swift

@@ -0,0 +1,10 @@
+//
+//  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)
+}

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.
     ///