@bigcrunch/react-native-ads 0.11.0 → 0.14.0

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

@@ -26,9 +26,21 @@ internal class AnalyticsClient {
     private var impressionContexts: [String: ImpressionContext] = [:]
     private let contextLock = NSLock()
 
+    /// Per-placement auction data from S2S responses (set by AdOrchestrator, consumed by trackAdImpression)
+    private var placementAuctionData: [String: AuctionData] = [:]
+
     /// Previous screen name for referrer tracking
     private var previousScreenName: String?
 
+    /// Current page URL (set by trackScreenView, used by all events)
+    private var currentPageUrl: String = ""
+
+    /// Current custom dimensions (set by trackScreenView, used by all events)
+    private var currentCustomDimensions: [String: String] = [:]
+
+    /// Current account type (set by setAccountType, used by all events)
+    private var currentAcctType: String = "guest"
+
     /// Batching for impressions (250ms delay)
     private var impressionBatch: [ImpressionBatchEvent] = []
     private var impressionBatchTimer: Timer?
@@ -127,15 +139,34 @@ internal class AnalyticsClient {
 
     // MARK: - Page View Tracking
 
+    /**
+     * Generate the default page URL from screen name
+     */
+    private func generatePageUrl(_ screenName: String) -> String {
+        let appName = BigCrunchAds.getAppConfig()?.appName ?? "app"
+        let sanitizedAppName = appName.lowercased()
+            .replacingOccurrences(of: " ", with: "-")
+            .addingPercentEncoding(withAllowedCharacters: .urlHostAllowed) ?? appName
+        let encodedScreen = screenName.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? screenName
+        return "https://\(sanitizedAppName).mobile.app/\(encodedScreen)"
+    }
+
     /**
      * Track a screen view
      *
-     * - Parameter screenName: Name of the screen being viewed
+     * - Parameters:
+     *   - screenName: Name of the screen being viewed
+     *   - options: Optional overrides for page URL, metadata, and custom dimensions
      */
-    func trackScreenView(_ screenName: String) {
+    func trackScreenView(_ screenName: String, options: ScreenViewOptions? = nil) {
         // Start new page view and get IDs
         let pageId = sessionManager.startPageView()
 
+        // Resolve page URL: explicit override > auto-generated
+        let pageUrl = options?.pageUrl ?? generatePageUrl(screenName)
+        currentPageUrl = pageUrl
+        currentCustomDimensions = options?.customDimensions ?? [:]
+
         // Get common event fields
         let common = getCommonEventFields()
 
@@ -155,7 +186,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: pageId,
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",  // page_url must be valid URL or empty - mobile doesn't have URLs
+            pageUrl: pageUrl,
             pageSearch: "",
             pageReferrer: "",  // page_referrer must be valid URL or empty
             browser: common.browser,
@@ -172,11 +203,12 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
-            customDimensions: [:]
+            customDimensions: currentCustomDimensions,
+            pageMetaData: options?.pageMeta
         )
 
         sendEvent(event, endpoint: "pageviews")
@@ -249,6 +281,41 @@ internal class AnalyticsClient {
         return impressionContexts[impressionId]
     }
 
+    // MARK: - Auction Data Storage
+
+    /**
+     * Store auction data for a placement (called by AdOrchestrator after S2S demand fetch)
+     */
+    func setAccountType(_ accountType: String) {
+        currentAcctType = accountType
+    }
+
+    func setAuctionData(placementId: String, auctionData: AuctionData) {
+        contextLock.lock()
+        placementAuctionData[placementId] = auctionData
+        contextLock.unlock()
+        BCLogger.debug("Stored auction data for placement: \(placementId) (channel: \(auctionData.demandChannel ?? "unknown"))")
+    }
+
+    /**
+     * Consume auction data for a placement (returns and removes stored data)
+     */
+    private func consumeAuctionData(placementId: String) -> AuctionData? {
+        contextLock.lock()
+        let data = placementAuctionData.removeValue(forKey: placementId)
+        contextLock.unlock()
+        return data
+    }
+
+    /**
+     * Compute min_bid_to_win: $0.01 above the higher of second-highest bid or floor price
+     */
+    private func computeMinBidToWin(_ auctionData: AuctionData?) -> Double {
+        guard let data = auctionData else { return 0.0 }
+        let baseline = max(data.secondHighestBid ?? 0.0, data.floorPrice ?? 0.0)
+        return baseline > 0 ? baseline + 0.01 : 0.0
+    }
+
     // MARK: - Impression Tracking
 
     /**
@@ -278,27 +345,31 @@ internal class AnalyticsClient {
             ? context.auctionData.auctionId!
             : UUID().uuidString
 
+        // Look up stored auction data (may have been set by AdOrchestrator)
+        let storedAuctionData = consumeAuctionData(placementId: context.placementId)
+        let effectiveAuctionData = storedAuctionData ?? context.auctionData
+
         // Create the impression record
         let impressionRecord = ImpressionRecord(
             slotId: context.placementId,
             gamUnit: context.gamAdUnit,
-            gamPriceBucket: "",
+            gamPriceBucket: effectiveAuctionData.gamPriceBucket ?? "",
             impressionId: context.impressionId,
             auctionId: auctionId,  // Must be valid UUID
             refreshCount: 0,
-            adBidder: context.auctionData.bidder ?? "",
+            adBidder: effectiveAuctionData.bidder ?? "",
             adSize: adSize,
-            adPrice: context.auctionData.bidPriceCpm ?? 0.0,
-            adFloorPrice: 0.0,
-            minBidToWin: 0.0,
+            adPrice: effectiveAuctionData.bidPriceCpm ?? 0.0,
+            adFloorPrice: effectiveAuctionData.floorPrice ?? 0.0,
+            minBidToWin: computeMinBidToWin(effectiveAuctionData),
             advertiserId: "",
             campaignId: "",
             lineItemId: "",
-            creativeId: context.auctionData.creativeId ?? "",
+            creativeId: effectiveAuctionData.creativeId ?? "",
             adAmznbid: "",
             adAmznp: "",
-            adDemandType: "",
-            demandChannel: "",
+            adDemandType: context.format,
+            demandChannel: effectiveAuctionData.demandChannel ?? "Google Ad Exchange",
             customDimensions: [:]
         )
 
@@ -313,7 +384,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",  // page_url must be valid URL or empty
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -330,11 +401,11 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
-            customDimensions: [:],
+            customDimensions: currentCustomDimensions,
             impressions: [impressionRecord]
         )
 
@@ -342,11 +413,13 @@ internal class AnalyticsClient {
     }
 
     /**
-     * Track an ad impression (simple version without auction data)
+     * Track an ad impression (simple version with auction data lookup)
      */
     func trackAdImpression(
         placementId: String,
         format: String,
+        gamAdUnit: String = "",
+        adSize: String = "",
         refreshCount: Int = 0,
         advertiserId: String? = nil,
         campaignId: String? = nil,
@@ -362,27 +435,35 @@ internal class AnalyticsClient {
         // 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)
+        // Look up stored auction data from S2S response
+        let auctionData = consumeAuctionData(placementId: placementId)
+
+        // auction_id: use S2S auction ID if available, otherwise generate one
+        let auctionId = auctionData?.auctionId?.isEmpty == false
+            ? auctionData!.auctionId!
+            : UUID().uuidString
+
+        // Create the impression record with auction data fields populated
         let impressionRecord = ImpressionRecord(
             slotId: placementId,
-            gamUnit: "",
-            gamPriceBucket: "",
+            gamUnit: gamAdUnit,
+            gamPriceBucket: auctionData?.gamPriceBucket ?? "",
             impressionId: UUID().uuidString,
-            auctionId: UUID().uuidString,  // auction_id is required and must be valid UUID
+            auctionId: auctionId,
             refreshCount: refreshCount,
-            adBidder: "",
-            adSize: "",
-            adPrice: 0.0,
-            adFloorPrice: 0.0,
-            minBidToWin: 0.0,
+            adBidder: auctionData?.bidder ?? "",
+            adSize: adSize,
+            adPrice: auctionData?.bidPriceCpm ?? 0.0,
+            adFloorPrice: auctionData?.floorPrice ?? 0.0,
+            minBidToWin: computeMinBidToWin(auctionData),
             advertiserId: advertiserId ?? "",
             campaignId: campaignId ?? "",
             lineItemId: lineItemId ?? "",
-            creativeId: creativeId ?? "",
+            creativeId: auctionData?.creativeId ?? creativeId ?? "",
             adAmznbid: "",
             adAmznp: "",
-            adDemandType: "",
-            demandChannel: "",
+            adDemandType: format,
+            demandChannel: auctionData?.demandChannel ?? "Google Ad Exchange",
             customDimensions: [:]
         )
 
@@ -397,7 +478,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",  // page_url must be valid URL or empty
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -414,11 +495,11 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,  // amzn_pub_id must be valid UUID
-            customDimensions: [:],
+            customDimensions: currentCustomDimensions,
             impressions: [impressionRecord]
         )
 
@@ -474,7 +555,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -491,11 +572,11 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,
-            customDimensions: [:],
+            customDimensions: currentCustomDimensions,
             click: clickData
         )
 
@@ -564,7 +645,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -581,7 +662,7 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,
@@ -631,7 +712,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -648,7 +729,7 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,
@@ -687,7 +768,7 @@ internal class AnalyticsClient {
             newUser: sessionManager.isNewUser,
             pageId: sessionManager.getOrCreatePageId(),
             sessionDepth: sessionManager.sessionDepth,
-            pageUrl: "",
+            pageUrl: currentPageUrl,
             pageSearch: "",
             pageReferrer: "",
             browser: common.browser,
@@ -704,11 +785,11 @@ internal class AnalyticsClient {
             utmContent: common.utmContent ?? "",
             gclid: "",
             fbclid: "",
-            acctType: "anonymous",
+            acctType: currentAcctType,
             diiSource: "",
             gamNetworkCode: gamNetworkCode,
             amznPubId: AnalyticsClient.nilUUID,
-            customDimensions: [:],  // Values would be [String] arrays per backend schema
+            customDimensions: [:],  // Engagement uses array-valued custom dimensions per backend schema
             engagedTime: engagedTime,
             timeOnPage: timeOnPage,
             scrollDepth: scrollDepth
@@ -761,6 +842,8 @@ internal class AnalyticsClient {
 
     /**
      * Flush all batched impression events
+     *
+     * Merges events with the same pageId into a single object with combined impressions array.
      */
     private func flushImpressionBatch() {
         impressionBatchLock.lock()
@@ -770,28 +853,40 @@ internal class AnalyticsClient {
         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)")
+        if events.isEmpty { return }
+
+        // Group by pageId and merge impressions into single objects
+        var merged: [String: ImpressionBatchEvent] = [:]
+        for event in events {
+            if var existing = merged[event.pageId] {
+                existing.impressions.append(contentsOf: event.impressions)
+                merged[event.pageId] = existing
+            } else {
+                merged[event.pageId] = event
+            }
+        }
+
+        let mergedEvents = Array(merged.values)
+
+        Task {
+            do {
+                let encoder = JSONEncoder()
+                let data = try encoder.encode(mergedEvents)
+                let json = String(data: data, encoding: .utf8)!
+                let url = "\(baseURL)/impressions"
+
+                BCLogger.debug("Sending \(mergedEvents.count) batched impression groups (\(events.count) total 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)")
             }
         }
     }
@@ -817,6 +912,8 @@ internal class AnalyticsClient {
 
     /**
      * Flush all batched viewability events
+     *
+     * Merges events with the same pageId into a single object with combined viewability array.
      */
     private func flushViewabilityBatch() {
         viewabilityBatchLock.lock()
@@ -826,28 +923,40 @@ internal class AnalyticsClient {
         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)")
+        if events.isEmpty { return }
+
+        // Group by pageId and merge viewability into single objects
+        var merged: [String: ViewabilityEvent] = [:]
+        for event in events {
+            if var existing = merged[event.pageId] {
+                existing.viewability.append(contentsOf: event.viewability)
+                merged[event.pageId] = existing
+            } else {
+                merged[event.pageId] = event
+            }
+        }
+
+        let mergedEvents = Array(merged.values)
+
+        Task {
+            do {
+                let encoder = JSONEncoder()
+                let data = try encoder.encode(mergedEvents)
+                let json = String(data: data, encoding: .utf8)!
+                let url = "\(baseURL)/viewability"
+
+                BCLogger.debug("Sending \(mergedEvents.count) batched viewability groups (\(events.count) total)")
+
+                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)")
             }
         }
     }

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

@@ -10,8 +10,8 @@ import Foundation
  *
  * Usage:
  * ```swift
- * let targeting = await bidRequestClient.fetchDemand(placement: placement)
- * // targeting is [String: String] with GAM custom targeting KVPs
+ * let bidResponse = await bidRequestClient.fetchDemand(placement: placement)
+ * // bidResponse contains targeting KVPs and auction metadata
  * ```
  */
 internal class BidRequestClient {
@@ -29,9 +29,15 @@ internal class BidRequestClient {
 
     // MARK: - Types
 
+    /// Bid response containing both targeting KVPs and auction metadata
+    internal struct BidResponse {
+        let targeting: [String: String]
+        let auctionData: AuctionData
+    }
+
     private struct PendingRequest {
         let placement: PlacementConfig
-        let continuation: CheckedContinuation<[String: String]?, Never>
+        let continuation: CheckedContinuation<BidResponse?, Never>
     }
 
     // MARK: - Init
@@ -59,7 +65,7 @@ internal class BidRequestClient {
      * - Parameter placement: The placement to fetch demand for
      * - Returns: Targeting KVPs to apply to GAM request, or nil
      */
-    func fetchDemand(placement: PlacementConfig) async -> [String: String]? {
+    func fetchDemand(placement: PlacementConfig) async -> BidResponse? {
         guard s2sConfig.enabled else {
             BCLogger.debug("BidRequestClient: S2S is disabled, skipping bid request")
             return nil
@@ -104,15 +110,15 @@ internal class BidRequestClient {
 
             // Distribute results to each pending continuation
             for pending in batch {
-                let targeting = results[pending.placement.placementId]
-                pending.continuation.resume(returning: targeting)
+                let bidResponse = results[pending.placement.placementId]
+                pending.continuation.resume(returning: bidResponse)
             }
         }
     }
 
     // MARK: - Request Building & Execution
 
-    private func executeBidRequest(placements: [PlacementConfig]) async -> [String: [String: String]] {
+    private func executeBidRequest(placements: [PlacementConfig]) async -> [String: BidResponse] {
         let requestBody = buildRequestJSON(placements: placements)
 
         guard let jsonData = try? JSONSerialization.data(withJSONObject: requestBody),
@@ -131,7 +137,7 @@ internal class BidRequestClient {
 
         switch result {
         case .success(let responseJson):
-            return parseResponse(responseJson)
+            return parseResponse(responseJson, placements: placements)
         case .failure(let error):
             BCLogger.error("BidRequestClient: Bid request failed: \(error)")
             return [:]
@@ -310,7 +316,7 @@ internal class BidRequestClient {
      *
      * Groups bids by impid, picks winner (highest price), copies ext.targeting.
      */
-    private func parseResponse(_ jsonString: String) -> [String: [String: String]] {
+    private func parseResponse(_ jsonString: String, placements: [PlacementConfig]) -> [String: BidResponse] {
         guard let data = jsonString.data(using: .utf8),
               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let seatbids = json["seatbid"] as? [[String: Any]] else {
@@ -318,10 +324,23 @@ internal class BidRequestClient {
             return [:]
         }
 
+        let auctionId = json["id"] as? String
+
+        // Build floor price lookup from placement configs
+        let floorPrices = Dictionary(uniqueKeysWithValues: placements.map { ($0.placementId, $0.floorPrice) })
+
         // Collect all bids grouped by impid
-        var bidsByImpId: [String: [(price: Double, targeting: [String: String])]] = [:]
+        struct BidInfo {
+            let price: Double
+            let targeting: [String: String]
+            let seat: String
+            let creativeId: String?
+        }
+
+        var bidsByImpId: [String: [BidInfo]] = [:]
 
         for seatbid in seatbids {
+            let seat = seatbid["seat"] as? String ?? ""
             guard let bids = seatbid["bid"] as? [[String: Any]] else { continue }
             for bid in bids {
                 guard let impid = bid["impid"] as? String,
@@ -330,17 +349,35 @@ internal class BidRequestClient {
                       let targeting = ext["targeting"] as? [String: String] else {
                     continue
                 }
-                bidsByImpId[impid, default: []].append((price: price, targeting: targeting))
+                let crid = bid["crid"] as? String
+                bidsByImpId[impid, default: []].append(BidInfo(
+                    price: price, targeting: targeting, seat: seat, creativeId: crid
+                ))
             }
         }
 
-        // Pick winner (highest price) for each impid
-        var results: [String: [String: String]] = [:]
+        // Pick winner (highest price) for each impid and compute auction metadata
+        var results: [String: BidResponse] = [:]
         for (impid, bids) in bidsByImpId {
-            if let winner = bids.max(by: { $0.price < $1.price }) {
-                results[impid] = winner.targeting
-                BCLogger.debug("BidRequestClient: Winner for \(impid): $\(winner.price)")
-            }
+            let sortedBids = bids.sorted { $0.price > $1.price }
+            guard let winner = sortedBids.first else { continue }
+
+            let secondHighestBid = sortedBids.count > 1 ? sortedBids[1].price : nil
+            let floorPrice = floorPrices[impid] ?? nil
+
+            let auctionData = AuctionData(
+                auctionId: auctionId,
+                bidder: winner.seat,
+                bidPriceCpm: winner.price,
+                creativeId: winner.creativeId,
+                gamPriceBucket: winner.targeting["hb_pb"],
+                floorPrice: floorPrice,
+                secondHighestBid: secondHighestBid,
+                demandChannel: "S2S"
+            )
+
+            results[impid] = BidResponse(targeting: winner.targeting, auctionData: auctionData)
+            BCLogger.debug("BidRequestClient: Winner for \(impid): $\(winner.price)")
         }
 
         BCLogger.info("BidRequestClient: Parsed \(results.count) winning bids")

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

@@ -74,7 +74,7 @@ internal final class DeviceContext {
     // MARK: - SDK Properties
 
     /// SDK version
-    static let SDK_VERSION = "0.11.0"
+    static let SDK_VERSION = "0.14.0"
     let sdkVersion: String = SDK_VERSION
 
     /// SDK platform (always "ios")