@bigcrunch/react-native-ads 0.4.0 → 0.5.0

package/ios/BigCrunchAds/Sources/Models/AdEvent.swift

@@ -0,0 +1,784 @@
+import Foundation
+
+// MARK: - Legacy Event (keeping for backward compatibility)
+
+/**
+ * Analytics event sent to BigCrunch backend
+ *
+ * All ad-related events (impressions, clicks, revenue) are tracked and sent
+ * to the analytics endpoint in this format.
+ */
+internal struct AdEvent: Codable {
+    let eventType: String // "screen_view", "ad_request", "ad_impression", "ad_revenue", "ad_click", "ad_viewable"
+    let placementId: String?
+    let format: String? // "banner", "interstitial", "rewarded"
+    let timestamp: Int64
+    let sessionId: String
+    let deviceInfo: DeviceInfo
+    let revenue: RevenueData?
+}
+
+/**
+ * Device and app information included with every event
+ */
+internal struct DeviceInfo: Codable {
+    let platform: String
+    let osVersion: String
+    let appVersion: String
+    let deviceId: String
+}
+
+/**
+ * Revenue data from ILRD (Impression-Level Revenue Data)
+ *
+ * Only present in ad_revenue events. Values are in micros (1/1,000,000 of currency unit).
+ */
+internal struct RevenueData: Codable {
+    let valueMicros: Int64
+    let currency: String
+}
+
+// MARK: - Enhanced Analytics Events (matching web SDK data model)
+
+/**
+ * Screen/Page view event - matches `/pageviews` endpoint
+ *
+ * Sent when a new screen is viewed. Contains session context and device info.
+ */
+internal struct PageViewEvent: Codable {
+    // Web schema common fields
+    let payloadVersion: String  // Must be semver format "x.y.z"
+    let configVersion: Int
+    let browserTimestamp: String  // ISO 8601 with milliseconds
+
+    // Session/user context
+    let sessionId: String
+    let userId: String
+    let propertyId: String
+    let newUser: Bool
+
+    // Page context
+    let pageId: String
+    let sessionDepth: Int
+    let pageUrl: String  // Must be valid URL or empty string (mobile uses empty)
+    let pageSearch: String  // Query string, empty for mobile
+    let pageReferrer: String  // Must be valid URL or empty string
+
+    // Device context (flattened)
+    let browser: String
+    let device: String
+    let os: String
+    let country: String
+    let region: String  // Must be 2 chars or empty
+
+    // Attribution
+    let sessionSource: String
+    let sessionMedium: String
+    let utmSource: String
+    let utmMedium: String
+    let utmCampaign: String
+    let utmTerm: String
+    let utmContent: String
+
+    // Click IDs for attribution
+    let gclid: String
+    let fbclid: String
+
+    // Additional required fields
+    let acctType: String  // "anonymous" for mobile
+    let diiSource: String  // empty for mobile
+    let gamNetworkCode: String
+    let amznPubId: String  // Must be valid UUID (nil UUID for empty)
+    let customDimensions: [String: String]
+
+    enum CodingKeys: String, CodingKey {
+        case payloadVersion = "payload_version"
+        case configVersion = "config_version"
+        case browserTimestamp = "browser_timestamp"
+        case sessionId = "session_id"
+        case userId = "user_id"
+        case propertyId = "property_id"
+        case newUser = "new_user"
+        case pageId = "page_id"
+        case sessionDepth = "session_depth"
+        case pageUrl = "page_url"
+        case pageSearch = "page_search"
+        case pageReferrer = "page_referrer"
+        case browser
+        case device
+        case os
+        case country
+        case region
+        case sessionSource = "session_source"
+        case sessionMedium = "session_medium"
+        case utmSource = "utm_source"
+        case utmMedium = "utm_medium"
+        case utmCampaign = "utm_campaign"
+        case utmTerm = "utm_term"
+        case utmContent = "utm_content"
+        case gclid
+        case fbclid
+        case acctType = "acct_type"
+        case diiSource = "dii_source"
+        case gamNetworkCode = "gam_network_code"
+        case amznPubId = "amzn_pub_id"
+        case customDimensions = "custom_dimensions"
+    }
+}
+
+/**
+ * Individual impression record - nested inside ImpressionBatchEvent
+ *
+ * Represents a single ad impression with auction/bid data.
+ */
+internal struct ImpressionRecord: Codable {
+    /// Placement identifier (slot_id in web SDK)
+    let slotId: String
+
+    /// GAM ad unit path
+    let gamUnit: String
+
+    /// GAM price bucket
+    let gamPriceBucket: String
+
+    /// Unique identifier for this impression
+    let impressionId: String
+
+    /// Auction ID (from Prebid) - REQUIRED, must be valid UUID
+    let auctionId: String
+
+    /// Refresh count for this placement
+    let refreshCount: Int
+
+    /// Winning bidder name
+    let adBidder: String
+
+    /// Ad size (e.g., "320x50")
+    let adSize: String
+
+    /// Bid price/revenue in CPM
+    let adPrice: Double
+
+    /// Floor price
+    let adFloorPrice: Double
+
+    /// Minimum bid to win
+    let minBidToWin: Double
+
+    /// Advertiser ID from GAM
+    let advertiserId: String
+
+    /// Campaign ID from GAM
+    let campaignId: String
+
+    /// Line item ID from GAM
+    let lineItemId: String
+
+    /// Creative ID from GAM response
+    let creativeId: String
+
+    /// Amazon bid data (if applicable)
+    let adAmznbid: String
+
+    /// Amazon price data (if applicable)
+    let adAmznp: String
+
+    /// Demand type (banner, video, etc.)
+    let adDemandType: String
+
+    /// Demand channel (e.g., "Prebid Header", "GAM Direct")
+    let demandChannel: String
+
+    /// Custom dimensions
+    let customDimensions: [String: String]
+
+    enum CodingKeys: String, CodingKey {
+        case slotId = "slot_id"
+        case gamUnit = "gam_unit"
+        case gamPriceBucket = "gam_price_bucket"
+        case impressionId = "impression_id"
+        case auctionId = "auction_id"
+        case refreshCount = "refresh_count"
+        case adBidder = "ad_bidder"
+        case adSize = "ad_size"
+        case adPrice = "ad_price"
+        case adFloorPrice = "ad_floor_price"
+        case minBidToWin = "min_bid_to_win"
+        case advertiserId = "advertiser_id"
+        case campaignId = "campaign_id"
+        case lineItemId = "line_item_id"
+        case creativeId = "creative_id"
+        case adAmznbid = "ad_amznbid"
+        case adAmznp = "ad_amznp"
+        case adDemandType = "ad_demand_type"
+        case demandChannel = "demand_channel"
+        case customDimensions = "custom_dimensions"
+    }
+}
+
+/**
+ * Impression batch event - matches `/impressions` endpoint
+ *
+ * Contains session/page context with nested array of impression records.
+ * This matches the web SDK format where impressions are batched with pageview context.
+ */
+internal struct ImpressionBatchEvent: Codable {
+    // Web schema common fields
+    let payloadVersion: String  // Must be semver format "x.y.z"
+    let configVersion: Int
+    let browserTimestamp: String  // ISO 8601 with milliseconds
+
+    // Session/user context
+    let sessionId: String
+    let userId: String
+    let propertyId: String
+    let newUser: Bool
+    let pageId: String
+    let sessionDepth: Int
+
+    // Page context
+    let pageUrl: String  // Must be valid URL or empty string
+    let pageSearch: String
+    let pageReferrer: String
+
+    // Device context (flattened)
+    let browser: String
+    let device: String
+    let os: String
+    let country: String
+    let region: String  // Must be 2 chars or empty
+
+    // Attribution
+    let sessionSource: String
+    let sessionMedium: String
+    let utmSource: String
+    let utmMedium: String
+    let utmCampaign: String
+    let utmTerm: String
+    let utmContent: String
+
+    // Click IDs for attribution
+    let gclid: String
+    let fbclid: String
+
+    // Additional required fields
+    let acctType: String
+    let diiSource: String
+    let gamNetworkCode: String
+    let amznPubId: String  // Must be valid UUID (nil UUID for empty)
+    let customDimensions: [String: String]
+
+    // Nested impressions array
+    let impressions: [ImpressionRecord]
+
+    enum CodingKeys: String, CodingKey {
+        case payloadVersion = "payload_version"
+        case configVersion = "config_version"
+        case browserTimestamp = "browser_timestamp"
+        case sessionId = "session_id"
+        case userId = "user_id"
+        case propertyId = "property_id"
+        case newUser = "new_user"
+        case pageId = "page_id"
+        case sessionDepth = "session_depth"
+        case pageUrl = "page_url"
+        case pageSearch = "page_search"
+        case pageReferrer = "page_referrer"
+        case browser
+        case device
+        case os
+        case country
+        case region
+        case sessionSource = "session_source"
+        case sessionMedium = "session_medium"
+        case utmSource = "utm_source"
+        case utmMedium = "utm_medium"
+        case utmCampaign = "utm_campaign"
+        case utmTerm = "utm_term"
+        case utmContent = "utm_content"
+        case gclid
+        case fbclid
+        case acctType = "acct_type"
+        case diiSource = "dii_source"
+        case gamNetworkCode = "gam_network_code"
+        case amznPubId = "amzn_pub_id"
+        case customDimensions = "custom_dimensions"
+        case impressions
+    }
+}
+
+/**
+ * Click data object nested inside ClickEvent
+ *
+ * Contains the click-specific fields per backend schema.
+ */
+internal struct ClickData: Codable {
+    /// Unique click identifier
+    let clickId: String
+
+    /// Placement identifier (slot_id in web SDK)
+    let slotId: String
+
+    /// Reference to the impression that was clicked - must be valid UUID
+    let impressionId: String
+
+    /// Refresh count for this placement
+    let refreshCount: Int
+
+    /// Amazon price data (if applicable)
+    let adAmznp: String
+
+    /// Winning bidder name
+    let adBidder: String
+
+    /// Ad size (e.g., "320x50")
+    let adSize: String
+
+    /// Advertiser ID from GAM
+    let advertiserId: String
+
+    /// Campaign ID from GAM
+    let campaignId: String
+
+    /// Line item ID from GAM
+    let lineItemId: String
+
+    /// Creative ID from GAM response
+    let creativeId: String
+
+    /// Demand type (banner, video, etc.)
+    let adDemandType: String
+
+    /// Demand channel (e.g., "Prebid Header", "GAM Direct")
+    let demandChannel: String
+
+    /// Custom dimensions - values must be string arrays per backend schema
+    let customDimensions: [String: [String]]
+
+    enum CodingKeys: String, CodingKey {
+        case clickId = "click_id"
+        case slotId = "slot_id"
+        case impressionId = "impression_id"
+        case refreshCount = "refresh_count"
+        case adAmznp = "ad_amznp"
+        case adBidder = "ad_bidder"
+        case adSize = "ad_size"
+        case advertiserId = "advertiser_id"
+        case campaignId = "campaign_id"
+        case lineItemId = "line_item_id"
+        case creativeId = "creative_id"
+        case adDemandType = "ad_demand_type"
+        case demandChannel = "demand_channel"
+        case customDimensions = "custom_dimensions"
+    }
+}
+
+/**
+ * Ad click event - matches `/clicks` endpoint
+ *
+ * Sent when a user clicks on an ad.
+ */
+internal struct ClickEvent: Codable {
+    // Web schema common fields
+    let payloadVersion: String  // Must be semver format "x.y.z"
+    let configVersion: Int
+    let browserTimestamp: String  // ISO 8601 with milliseconds
+
+    // Session/user context
+    let sessionId: String
+    let userId: String
+    let propertyId: String
+    let newUser: Bool
+    let pageId: String
+    let sessionDepth: Int
+
+    // Page context
+    let pageUrl: String
+    let pageSearch: String
+    let pageReferrer: String
+
+    // Device context (flattened)
+    let browser: String
+    let device: String
+    let os: String
+    let country: String
+    let region: String  // Must be 2 chars or empty
+
+    // Attribution
+    let sessionSource: String
+    let sessionMedium: String
+    let utmSource: String
+    let utmMedium: String
+    let utmCampaign: String
+    let utmTerm: String
+    let utmContent: String
+
+    // Click IDs
+    let gclid: String
+    let fbclid: String
+
+    // Additional required fields
+    let acctType: String
+    let diiSource: String
+    let gamNetworkCode: String
+    let amznPubId: String
+    let customDimensions: [String: String]
+
+    // Click-specific fields (nested click object per schema)
+    let click: ClickData
+
+    enum CodingKeys: String, CodingKey {
+        case payloadVersion = "payload_version"
+        case configVersion = "config_version"
+        case browserTimestamp = "browser_timestamp"
+        case sessionId = "session_id"
+        case userId = "user_id"
+        case propertyId = "property_id"
+        case newUser = "new_user"
+        case pageId = "page_id"
+        case sessionDepth = "session_depth"
+        case pageUrl = "page_url"
+        case pageSearch = "page_search"
+        case pageReferrer = "page_referrer"
+        case browser
+        case device
+        case os
+        case country
+        case region
+        case sessionSource = "session_source"
+        case sessionMedium = "session_medium"
+        case utmSource = "utm_source"
+        case utmMedium = "utm_medium"
+        case utmCampaign = "utm_campaign"
+        case utmTerm = "utm_term"
+        case utmContent = "utm_content"
+        case gclid
+        case fbclid
+        case acctType = "acct_type"
+        case diiSource = "dii_source"
+        case gamNetworkCode = "gam_network_code"
+        case amznPubId = "amzn_pub_id"
+        case customDimensions = "custom_dimensions"
+        case click
+    }
+}
+
+/**
+ * Viewability data object nested inside ViewabilityEvent
+ *
+ * Contains the per-slot viewability metrics.
+ */
+internal struct ViewabilityData: Codable {
+    /// Placement identifier (slot_id in web SDK)
+    let slotId: String
+
+    /// Reference to the impression - must be valid UUID
+    let impressionId: String
+
+    /// Refresh count for this placement
+    let refreshCount: Int
+
+    /// Amazon price data (if applicable)
+    let adAmznp: String
+
+    /// Winning bidder name
+    let adBidder: String
+
+    /// Ad size (e.g., "320x50")
+    let adSize: String
+
+    /// Advertiser ID from GAM
+    let advertiserId: String
+
+    /// Campaign ID from GAM
+    let campaignId: String
+
+    /// Line item ID from GAM
+    let lineItemId: String
+
+    /// Creative ID from GAM response
+    let creativeId: String
+
+    /// Demand type (banner, video, etc.)
+    let adDemandType: String
+
+    /// Demand channel (e.g., "Prebid Header", "GAM Direct")
+    let demandChannel: String
+
+    /// Custom dimensions
+    let customDimensions: [String: [String]]
+
+    enum CodingKeys: String, CodingKey {
+        case slotId = "slot_id"
+        case impressionId = "impression_id"
+        case refreshCount = "refresh_count"
+        case adAmznp = "ad_amznp"
+        case adBidder = "ad_bidder"
+        case adSize = "ad_size"
+        case advertiserId = "advertiser_id"
+        case campaignId = "campaign_id"
+        case lineItemId = "line_item_id"
+        case creativeId = "creative_id"
+        case adDemandType = "ad_demand_type"
+        case demandChannel = "demand_channel"
+        case customDimensions = "custom_dimensions"
+    }
+}
+
+/**
+ * Viewability event - matches `/viewability` endpoint
+ *
+ * Sent when an ad meets viewability thresholds (e.g., 50% visible for 1 second).
+ * Contains session/page context with nested viewability array.
+ */
+internal struct ViewabilityEvent: Codable {
+    // Web schema common fields
+    let payloadVersion: String  // Must be semver format "x.y.z"
+    let configVersion: Int
+    let browserTimestamp: String  // ISO 8601 with milliseconds
+
+    // Session/user context
+    let sessionId: String
+    let userId: String
+    let propertyId: String
+    let newUser: Bool
+    let pageId: String
+    let sessionDepth: Int
+
+    // Page context
+    let pageUrl: String
+    let pageSearch: String
+    let pageReferrer: String
+
+    // Device context (flattened)
+    let browser: String
+    let device: String
+    let os: String
+    let country: String
+    let region: String  // Must be 2 chars or empty
+
+    // Attribution
+    let sessionSource: String
+    let sessionMedium: String
+    let utmSource: String
+    let utmMedium: String
+    let utmCampaign: String
+    let utmTerm: String
+    let utmContent: String
+
+    // Click IDs
+    let gclid: String
+    let fbclid: String
+
+    // Additional required fields
+    let acctType: String
+    let diiSource: String
+    let gamNetworkCode: String
+    let amznPubId: String
+
+    // Nested viewability array (per backend schema)
+    let viewability: [ViewabilityData]
+
+    enum CodingKeys: String, CodingKey {
+        case payloadVersion = "payload_version"
+        case configVersion = "config_version"
+        case browserTimestamp = "browser_timestamp"
+        case sessionId = "session_id"
+        case userId = "user_id"
+        case propertyId = "property_id"
+        case newUser = "new_user"
+        case pageId = "page_id"
+        case sessionDepth = "session_depth"
+        case pageUrl = "page_url"
+        case pageSearch = "page_search"
+        case pageReferrer = "page_referrer"
+        case browser
+        case device
+        case os
+        case country
+        case region
+        case sessionSource = "session_source"
+        case sessionMedium = "session_medium"
+        case utmSource = "utm_source"
+        case utmMedium = "utm_medium"
+        case utmCampaign = "utm_campaign"
+        case utmTerm = "utm_term"
+        case utmContent = "utm_content"
+        case gclid
+        case fbclid
+        case acctType = "acct_type"
+        case diiSource = "dii_source"
+        case gamNetworkCode = "gam_network_code"
+        case amznPubId = "amzn_pub_id"
+        case viewability
+    }
+}
+
+/**
+ * Engagement event - matches `/engagement` endpoint
+ *
+ * Tracks user engagement with content/screens.
+ */
+internal struct EngagementEvent: Codable {
+    // Web schema common fields
+    let payloadVersion: String  // Must be semver format "x.y.z"
+    let configVersion: Int
+    let browserTimestamp: String  // ISO 8601 with milliseconds
+
+    // Session/user context
+    let sessionId: String
+    let userId: String
+    let propertyId: String
+    let newUser: Bool
+    let pageId: String
+    let sessionDepth: Int
+
+    // Page context
+    let pageUrl: String
+    let pageSearch: String
+    let pageReferrer: String
+
+    // Device context (flattened)
+    let browser: String
+    let device: String
+    let os: String
+    let country: String
+    let region: String  // Must be 2 chars or empty
+
+    // Attribution
+    let sessionSource: String
+    let sessionMedium: String
+    let utmSource: String
+    let utmMedium: String
+    let utmCampaign: String
+    let utmTerm: String
+    let utmContent: String
+
+    // Click IDs
+    let gclid: String
+    let fbclid: String
+
+    // Additional required fields
+    let acctType: String
+    let diiSource: String
+    let gamNetworkCode: String
+    let amznPubId: String
+
+    /// Custom dimensions - values must be string arrays per backend schema
+    let customDimensions: [String: [String]]
+
+    // Engagement-specific fields
+    /// Time actively engaged in seconds
+    let engagedTime: Int
+
+    /// Total time on page/screen in seconds
+    let timeOnPage: Int
+
+    /// Maximum scroll depth percentage (0-100)
+    let scrollDepth: Int
+
+    enum CodingKeys: String, CodingKey {
+        case payloadVersion = "payload_version"
+        case configVersion = "config_version"
+        case browserTimestamp = "browser_timestamp"
+        case sessionId = "session_id"
+        case userId = "user_id"
+        case propertyId = "property_id"
+        case newUser = "new_user"
+        case pageId = "page_id"
+        case sessionDepth = "session_depth"
+        case pageUrl = "page_url"
+        case pageSearch = "page_search"
+        case pageReferrer = "page_referrer"
+        case browser
+        case device
+        case os
+        case country
+        case region
+        case sessionSource = "session_source"
+        case sessionMedium = "session_medium"
+        case utmSource = "utm_source"
+        case utmMedium = "utm_medium"
+        case utmCampaign = "utm_campaign"
+        case utmTerm = "utm_term"
+        case utmContent = "utm_content"
+        case gclid
+        case fbclid
+        case acctType = "acct_type"
+        case diiSource = "dii_source"
+        case gamNetworkCode = "gam_network_code"
+        case amznPubId = "amzn_pub_id"
+        case customDimensions = "custom_dimensions"
+        case engagedTime = "engaged_time"
+        case timeOnPage = "time_on_page"
+        case scrollDepth = "scroll_depth"
+    }
+}
+
+// MARK: - Auction Data
+
+/**
+ * Auction data from Prebid response
+ *
+ * Captures bidding information for analytics.
+ */
+internal struct AuctionData {
+    /// Prebid auction ID
+    let auctionId: String?
+
+    /// Winning bidder name
+    let bidder: String?
+
+    /// Winning bid price in CPM
+    let bidPriceCpm: Double?
+
+    /// Creative ID from winning bid
+    let creativeId: String?
+
+    /// Empty auction data
+    static let empty = AuctionData(auctionId: nil, bidder: nil, bidPriceCpm: nil, creativeId: nil)
+}
+
+// MARK: - Impression Context
+
+/**
+ * Context for tracking an ad impression
+ *
+ * Aggregates all data needed to track an impression through its lifecycle.
+ */
+internal struct ImpressionContext {
+    /// Unique impression identifier
+    let impressionId: String
+
+    /// Placement configuration
+    let placementId: String
+    let gamAdUnit: String
+    let format: String
+
+    /// Size (for banners)
+    let width: Int?
+    let height: Int?
+
+    /// Auction data (populated after Prebid response)
+    var auctionData: AuctionData
+
+    /// Timestamp when impression was created
+    let createdAt: Int64
+
+    init(
+        placementId: String,
+        gamAdUnit: String,
+        format: String,
+        width: Int? = nil,
+        height: Int? = nil
+    ) {
+        self.impressionId = UUID().uuidString
+        self.placementId = placementId
+        self.gamAdUnit = gamAdUnit
+        self.format = format
+        self.width = width
+        self.height = height
+        self.auctionData = .empty
+        self.createdAt = Int64(Date().timeIntervalSince1970 * 1000)
+    }
+}