@bigcrunch/react-native-ads 0.4.0 → 0.6.0

package/ios/BigCrunchAds/Sources/Core/AnalyticsClient.swift

@@ -0,0 +1,874 @@
+import Foundation
+import UIKit
+
+/**
+ * Analytics client for tracking ad events
+ *
+ * AnalyticsClient sends all ad-related events to the BigCrunch pipeline:
+ * - Page/screen views → `/pageviews`
+ * - Ad impressions (includes request + auction + revenue) → `/impressions`
+ * - Ad clicks → `/clicks`
+ * - Ad viewability → `/viewability`
+ * - User engagement → `/engagement`
+ *
+ * All events are fire-and-forget (non-blocking) and sent asynchronously.
+ * Failures are logged but do not propagate to the caller.
+ */
+internal class AnalyticsClient {
+
+    private let httpClient: HTTPClient
+    private let baseURL: String
+
+    /// Nil UUID for fields that require UUID format but have no value
+    private static let nilUUID = "00000000-0000-0000-0000-000000000000"
+
+    /// Track impression contexts for correlating events
+    private var impressionContexts: [String: ImpressionContext] = [:]
+    private let contextLock = NSLock()
+
+    /// Previous screen name for referrer tracking
+    private var previousScreenName: String?
+
+    /// Batching for impressions (250ms delay)
+    private var impressionBatch: [ImpressionBatchEvent] = []
+    private var impressionBatchTimer: Timer?
+    private let impressionBatchLock = NSLock()
+
+    /// Batching for viewability (250ms delay)
+    private var viewabilityBatch: [ViewabilityEvent] = []
+    private var viewabilityBatchTimer: Timer?
+    private let viewabilityBatchLock = NSLock()
+
+    init(httpClient: HTTPClient, baseURL: String) {
+        self.httpClient = httpClient
+        self.baseURL = baseURL
+    }
+
+    // MARK: - Session Context
+
+    private var sessionManager: SessionManager {
+        return SessionManager.shared
+    }
+
+    private var propertyId: String {
+        return BigCrunchAds.propertyId
+    }
+
+    // MARK: - Event Sending
+
+    /**
+     * Send an event to a specific endpoint (fire-and-forget)
+     * Wraps single event in an array as required by server
+     */
+    private func sendEvent<T: Encodable>(_ event: T, endpoint: String) {
+        Task {
+            do {
+                let encoder = JSONEncoder()
+                // Wrap single event in array as server expects arrays
+                let eventArray = [event]
+                let data = try encoder.encode(eventArray)
+                let json = String(data: data, encoding: .utf8)!
+                let url = "\(baseURL)/\(endpoint)"
+
+                BCLogger.debug("Sending event to: \(endpoint)")
+
+                let result = await httpClient.post(url: url, body: json)
+
+                switch result {
+                case .success:
+                    BCLogger.verbose("Event sent successfully: \(endpoint)")
+                case .failure(let error):
+                    BCLogger.warning("Failed to send event: \(endpoint) - \(error)")
+                }
+            } catch {
+                BCLogger.error("Error sending event: \(error)")
+            }
+        }
+    }
+
+    // MARK: - Common Event Fields
+
+    /**
+     * Get common web schema fields (device context, attribution, etc.)
+     * Returns a tuple with all the common fields needed for events
+     */
+    private func getCommonEventFields() -> (
+        browser: String,
+        device: String,
+        os: String,
+        country: String,
+        region: String,
+        sessionSource: String,
+        sessionMedium: String,
+        utmSource: String?,
+        utmMedium: String?,
+        utmCampaign: String?,
+        utmTerm: String?,
+        utmContent: String?
+    ) {
+        let deviceContext = DeviceContext.shared
+        let webFields = deviceContext.getWebSchemaFields()
+
+        return (
+            browser: webFields["browser"] as! String,
+            device: webFields["device"] as! String,
+            os: webFields["os"] as! String,
+            country: webFields["country"] as! String,
+            region: webFields["region"] as! String,
+            sessionSource: sessionManager.sessionSource,
+            sessionMedium: sessionManager.sessionMedium,
+            utmSource: sessionManager.utmSource,
+            utmMedium: sessionManager.utmMedium,
+            utmCampaign: sessionManager.utmCampaign,
+            utmTerm: sessionManager.utmTerm,
+            utmContent: sessionManager.utmContent
+        )
+    }
+
+    // MARK: - Page View Tracking
+
+    /**
+     * Track a screen view
+     *
+     * - Parameter screenName: Name of the screen being viewed
+     */
+    func trackScreenView(_ screenName: String) {
+        // Start new page view and get IDs
+        let pageId = sessionManager.startPageView()
+
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        let event = PageViewEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: pageId,
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",  // page_url must be valid URL or empty - mobile doesn't have URLs
+            pageSearch: "",
+            pageReferrer: "",  // page_referrer must be valid URL or empty
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
+            customDimensions: [:]
+        )
+
+        sendEvent(event, endpoint: "pageviews")
+
+        // Update previous screen for next referrer
+        previousScreenName = screenName
+    }
+
+    /**
+     * Track an ad request
+     *
+     * - Parameters:
+     *   - placementId: Placement identifier
+     *   - format: Ad format (banner, interstitial, rewarded)
+     */
+    func trackAdRequest(placementId: String, format: String) {
+        // For now, this is a placeholder as ad requests are tracked via createImpressionContext
+        // We may expand this in the future to track requests that don't result in impressions
+        print("[BigCrunchAds] Ad request tracked: \(placementId) format: \(format)")
+    }
+
+    // MARK: - Impression Context Management
+
+    /**
+     * Create and store an impression context for tracking
+     *
+     * Call this when starting to load an ad to generate an impression ID.
+     */
+    func createImpressionContext(
+        placementId: String,
+        gamAdUnit: String,
+        format: String,
+        width: Int? = nil,
+        height: Int? = nil
+    ) -> ImpressionContext {
+        let context = ImpressionContext(
+            placementId: placementId,
+            gamAdUnit: gamAdUnit,
+            format: format,
+            width: width,
+            height: height
+        )
+
+        contextLock.lock()
+        impressionContexts[context.impressionId] = context
+        contextLock.unlock()
+
+        BCLogger.debug("Created impression context: \(context.impressionId) for \(placementId)")
+
+        return context
+    }
+
+    /**
+     * Update auction data for an impression context
+     */
+    func updateAuctionData(impressionId: String, auctionData: AuctionData) {
+        contextLock.lock()
+        impressionContexts[impressionId]?.auctionData = auctionData
+        contextLock.unlock()
+
+        BCLogger.debug("Updated auction data for impression: \(impressionId)")
+    }
+
+    /**
+     * Get impression context by ID
+     */
+    func getImpressionContext(_ impressionId: String) -> ImpressionContext? {
+        contextLock.lock()
+        defer { contextLock.unlock() }
+        return impressionContexts[impressionId]
+    }
+
+    // MARK: - Impression Tracking
+
+    /**
+     * Track an ad impression with auction data
+     *
+     * - Parameter context: The impression context with all tracking data
+     */
+    func trackAdImpression(context: ImpressionContext) {
+        let adSize: String
+        if let width = context.width, let height = context.height {
+            adSize = "\(width)x\(height)"
+        } else {
+            adSize = ""
+        }
+
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        // auction_id is required and must be a valid UUID - generate one if not provided
+        let auctionId = context.auctionData.auctionId?.isEmpty == false
+            ? context.auctionData.auctionId!
+            : UUID().uuidString
+
+        // Create the impression record
+        let impressionRecord = ImpressionRecord(
+            slotId: context.placementId,
+            gamUnit: context.gamAdUnit,
+            gamPriceBucket: "",
+            impressionId: context.impressionId,
+            auctionId: auctionId,  // Must be valid UUID
+            refreshCount: 0,
+            adBidder: context.auctionData.bidder ?? "",
+            adSize: adSize,
+            adPrice: context.auctionData.bidPriceCpm ?? 0.0,
+            adFloorPrice: 0.0,
+            minBidToWin: 0.0,
+            advertiserId: "",
+            campaignId: "",
+            lineItemId: "",
+            creativeId: context.auctionData.creativeId ?? "",
+            adAmznbid: "",
+            adAmznp: "",
+            adDemandType: "",
+            demandChannel: "",
+            customDimensions: [:]
+        )
+
+        // Wrap in batch event with session context
+        let batchEvent = ImpressionBatchEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",  // page_url must be valid URL or empty
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
+            customDimensions: [:],
+            impressions: [impressionRecord]
+        )
+
+        batchImpressionEvent(batchEvent)
+    }
+
+    /**
+     * Track an ad impression (simple version without auction data)
+     */
+    func trackAdImpression(
+        placementId: String,
+        format: String,
+        refreshCount: Int = 0,
+        advertiserId: String? = nil,
+        campaignId: String? = nil,
+        lineItemId: String? = nil,
+        creativeId: String? = nil
+    ) {
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        // Create the impression record with generated auction_id (required)
+        let impressionRecord = ImpressionRecord(
+            slotId: placementId,
+            gamUnit: "",
+            gamPriceBucket: "",
+            impressionId: UUID().uuidString,
+            auctionId: UUID().uuidString,  // auction_id is required and must be valid UUID
+            refreshCount: refreshCount,
+            adBidder: "",
+            adSize: "",
+            adPrice: 0.0,
+            adFloorPrice: 0.0,
+            minBidToWin: 0.0,
+            advertiserId: advertiserId ?? "",
+            campaignId: campaignId ?? "",
+            lineItemId: lineItemId ?? "",
+            creativeId: creativeId ?? "",
+            adAmznbid: "",
+            adAmznp: "",
+            adDemandType: "",
+            demandChannel: "",
+            customDimensions: [:]
+        )
+
+        // Wrap in batch event with session context
+        let batchEvent = ImpressionBatchEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",  // page_url must be valid URL or empty
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
+            customDimensions: [:],
+            impressions: [impressionRecord]
+        )
+
+        batchImpressionEvent(batchEvent)
+    }
+
+    // MARK: - Click Tracking
+
+    /**
+     * Track an ad click with impression context
+     *
+     * - Parameters:
+     *   - impressionId: The impression that was clicked
+     *   - placementId: Placement ID
+     *   - format: Ad format
+     */
+    func trackAdClick(impressionId: String, placementId: String, format: String) {
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        // Create nested click data per backend schema
+        // Note: customDimensions values must be string arrays per backend validation
+        let clickData = ClickData(
+            clickId: UUID().uuidString,
+            slotId: placementId,
+            impressionId: impressionId.isEmpty ? UUID().uuidString : impressionId,  // Must be valid UUID
+            refreshCount: 0,
+            adAmznp: "",
+            adBidder: "",
+            adSize: "",
+            advertiserId: "",
+            campaignId: "",
+            lineItemId: "",
+            creativeId: "",
+            adDemandType: "",
+            demandChannel: "",
+            customDimensions: [:]  // Empty dict - values would be [String] arrays
+        )
+
+        let event = ClickEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,
+            customDimensions: [:],
+            click: clickData
+        )
+
+        sendEvent(event, endpoint: "clicks")
+    }
+
+    /**
+     * Track an ad click (simple version without impression ID)
+     */
+    func trackAdClick(placementId: String, format: String) {
+        trackAdClick(impressionId: "", placementId: placementId, format: format)
+    }
+
+    // MARK: - Viewability Tracking
+
+    /**
+     * Track ad viewability with impression context
+     *
+     * - Parameters:
+     *   - impressionId: The impression that became viewable (must be valid UUID)
+     *   - placementId: Placement ID (used as slot_id)
+     *   - format: Ad format (not sent directly, used for logging)
+     *   - viewableTimeMs: Time the ad was viewable in milliseconds (not in current schema)
+     *   - percentVisible: Percentage of ad that was visible (not in current schema)
+     */
+    func trackAdViewable(
+        impressionId: String,
+        placementId: String,
+        format: String,
+        viewableTimeMs: Int64,
+        percentVisible: Int
+    ) {
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        // Create viewability data with nested structure per backend schema
+        let viewabilityData = ViewabilityData(
+            slotId: placementId,
+            impressionId: impressionId.isEmpty ? UUID().uuidString : impressionId,  // Must be valid UUID
+            refreshCount: 0,
+            adAmznp: "",
+            adBidder: "",
+            adSize: "",
+            advertiserId: "",
+            campaignId: "",
+            lineItemId: "",
+            creativeId: "",
+            adDemandType: "",
+            demandChannel: "",
+            customDimensions: [:]
+        )
+
+        let event = ViewabilityEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,
+            viewability: [viewabilityData]
+        )
+
+        batchViewabilityEvent(event)
+    }
+
+    /**
+     * Track ad viewability (simple version without metrics)
+     */
+    func trackAdViewable(placementId: String, format: String) {
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        // Create viewability data with nested structure per backend schema
+        let viewabilityData = ViewabilityData(
+            slotId: placementId,
+            impressionId: UUID().uuidString,  // Generate UUID since none provided
+            refreshCount: 0,
+            adAmznp: "",
+            adBidder: "",
+            adSize: "",
+            advertiserId: "",
+            campaignId: "",
+            lineItemId: "",
+            creativeId: "",
+            adDemandType: "",
+            demandChannel: "",
+            customDimensions: [:]
+        )
+
+        let event = ViewabilityEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,
+            viewability: [viewabilityData]
+        )
+        batchViewabilityEvent(event)
+    }
+
+    // MARK: - Engagement Tracking
+
+    /**
+     * Track user engagement with content
+     *
+     * - Parameters:
+     *   - engagedTime: Time actively engaged in seconds
+     *   - timeOnPage: Total time on page/screen in seconds
+     *   - scrollDepth: Maximum scroll depth percentage (0-100)
+     */
+    func trackEngagement(engagedTime: Int, timeOnPage: Int, scrollDepth: Int = 0) {
+        // Get common event fields
+        let common = getCommonEventFields()
+
+        // Get GAM network code from config if available
+        let gamNetworkCode = BigCrunchAds.getConfigManager().getGamNetworkCode() ?? ""
+
+        // Region must be 2 chars or empty per backend validation
+        let regionCode = common.region.count == 2 ? common.region : ""
+
+        let event = EngagementEvent(
+            payloadVersion: "1.0.0",  // Must be semver format
+            configVersion: 1,
+            browserTimestamp: sessionManager.getCurrentTimestamp(),
+            sessionId: sessionManager.sessionId,
+            userId: sessionManager.userId,
+            propertyId: propertyId,
+            newUser: sessionManager.isNewUser,
+            pageId: sessionManager.getOrCreatePageId(),
+            sessionDepth: sessionManager.sessionDepth,
+            pageUrl: "",
+            pageSearch: "",
+            pageReferrer: "",
+            browser: common.browser,
+            device: common.device,
+            os: common.os,
+            country: common.country,
+            region: regionCode,
+            sessionSource: common.sessionSource,
+            sessionMedium: common.sessionMedium,
+            utmSource: common.utmSource ?? "",
+            utmMedium: common.utmMedium ?? "",
+            utmCampaign: common.utmCampaign ?? "",
+            utmTerm: common.utmTerm ?? "",
+            utmContent: common.utmContent ?? "",
+            gclid: "",
+            fbclid: "",
+            acctType: "anonymous",
+            diiSource: "",
+            gamNetworkCode: gamNetworkCode,
+            amznPubId: AnalyticsClient.nilUUID,
+            customDimensions: [:],  // Values would be [String] arrays per backend schema
+            engagedTime: engagedTime,
+            timeOnPage: timeOnPage,
+            scrollDepth: scrollDepth
+        )
+
+        sendEvent(event, endpoint: "engagement")
+    }
+
+    // MARK: - Revenue Tracking
+
+    /**
+     * Track ad revenue from ILRD (Impression-Level Revenue Data)
+     *
+     * Note: Revenue is now primarily tracked via the impression event's bidPriceCpm field.
+     * This method logs revenue data for debugging but does not send a separate event.
+     *
+     * - Parameters:
+     *   - placementId: The placement ID
+     *   - format: Ad format (banner, interstitial, rewarded)
+     *   - valueMicros: Revenue value in micros (1 micro = 0.000001 of currency)
+     *   - currency: ISO 4217 currency code (e.g., "USD")
+     */
+    func trackAdRevenue(placementId: String, format: String, valueMicros: Int64, currency: String) {
+        // Revenue is now tracked via ImpressionEvent.bidPriceCpm
+        // This method is kept for backwards compatibility and logging
+        let valueInCurrency = Double(valueMicros) / 1_000_000.0
+        BCLogger.debug("Ad revenue: \(placementId) (\(format)) - \(valueInCurrency) \(currency)")
+    }
+
+    // MARK: - Batching Helpers
+
+    /**
+     * Add impression event to batch queue
+     *
+     * Batches impressions for 250ms before sending to reduce network requests.
+     */
+    private func batchImpressionEvent(_ event: ImpressionBatchEvent) {
+        impressionBatchLock.lock()
+        impressionBatch.append(event)
+
+        // Start timer if not already running
+        if impressionBatchTimer == nil {
+            impressionBatchTimer = Timer.scheduledTimer(withTimeInterval: 0.25, repeats: false) { [weak self] _ in
+                self?.flushImpressionBatch()
+            }
+        }
+
+        impressionBatchLock.unlock()
+    }
+
+    /**
+     * Flush all batched impression events
+     */
+    private func flushImpressionBatch() {
+        impressionBatchLock.lock()
+        let events = impressionBatch
+        impressionBatch.removeAll()
+        impressionBatchTimer?.invalidate()
+        impressionBatchTimer = nil
+        impressionBatchLock.unlock()
+
+        // Send batched events as array
+        if !events.isEmpty {
+            Task {
+                do {
+                    let encoder = JSONEncoder()
+                    let data = try encoder.encode(events)
+                    let json = String(data: data, encoding: .utf8)!
+                    let url = "\(baseURL)/impressions"
+
+                    BCLogger.debug("Sending \(events.count) batched impressions")
+
+                    let result = await httpClient.post(url: url, body: json)
+
+                    switch result {
+                    case .success:
+                        BCLogger.verbose("Impression batch sent successfully")
+                    case .failure(let error):
+                        BCLogger.warning("Failed to send impression batch: \(error)")
+                    }
+                } catch {
+                    BCLogger.error("Error sending impression batch: \(error)")
+                }
+            }
+        }
+    }
+
+    /**
+     * Add viewability event to batch queue
+     *
+     * Batches viewability events for 250ms before sending to reduce network requests.
+     */
+    private func batchViewabilityEvent(_ event: ViewabilityEvent) {
+        viewabilityBatchLock.lock()
+        viewabilityBatch.append(event)
+
+        // Start timer if not already running
+        if viewabilityBatchTimer == nil {
+            viewabilityBatchTimer = Timer.scheduledTimer(withTimeInterval: 0.25, repeats: false) { [weak self] _ in
+                self?.flushViewabilityBatch()
+            }
+        }
+
+        viewabilityBatchLock.unlock()
+    }
+
+    /**
+     * Flush all batched viewability events
+     */
+    private func flushViewabilityBatch() {
+        viewabilityBatchLock.lock()
+        let events = viewabilityBatch
+        viewabilityBatch.removeAll()
+        viewabilityBatchTimer?.invalidate()
+        viewabilityBatchTimer = nil
+        viewabilityBatchLock.unlock()
+
+        // Send batched events as array
+        if !events.isEmpty {
+            Task {
+                do {
+                    let encoder = JSONEncoder()
+                    let data = try encoder.encode(events)
+                    let json = String(data: data, encoding: .utf8)!
+                    let url = "\(baseURL)/viewability"
+
+                    BCLogger.debug("Sending \(events.count) batched viewability events")
+
+                    let result = await httpClient.post(url: url, body: json)
+
+                    switch result {
+                    case .success:
+                        BCLogger.verbose("Viewability batch sent successfully")
+                    case .failure(let error):
+                        BCLogger.warning("Failed to send viewability batch: \(error)")
+                    }
+                } catch {
+                    BCLogger.error("Error sending viewability batch: \(error)")
+                }
+            }
+        }
+    }
+
+    // MARK: - Cleanup
+
+    /**
+     * Remove an impression context (call when ad is destroyed)
+     */
+    func removeImpressionContext(_ impressionId: String) {
+        contextLock.lock()
+        impressionContexts.removeValue(forKey: impressionId)
+        contextLock.unlock()
+    }
+
+    /**
+     * Clear all impression contexts
+     */
+    func clearImpressionContexts() {
+        contextLock.lock()
+        impressionContexts.removeAll()
+        contextLock.unlock()
+    }
+}