@bigcrunch/react-native-ads 0.4.0 → 0.5.0

package/android/bigcrunch-ads/com/bigcrunch/ads/core/SessionManager.kt

@@ -0,0 +1,330 @@
+package com.bigcrunch.ads.core
+
+import com.bigcrunch.ads.internal.BCLogger
+import com.bigcrunch.ads.internal.KeyValueStore
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicInteger
+import java.util.concurrent.atomic.AtomicLong
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * SessionManager handles session and user identification for analytics
+ *
+ * Manages:
+ * - user_id: Persistent UUID stored across app launches (identifies a user/device)
+ * - session_id: New UUID generated per app launch (identifies a session)
+ * - session_depth: Counter incremented per screen view within a session
+ * - page_id: New UUID generated per screen/page view
+ *
+ * Thread-safe implementation ensures consistent IDs across all analytics events.
+ */
+internal class SessionManager private constructor(private val storage: KeyValueStore) {
+
+    companion object {
+        private const val TAG = "SessionManager"
+
+        private const val KEY_USER_ID = "user_id"
+        private const val KEY_SESSION_COUNT = "session_count"
+        private const val KEY_SESSION_START_TIME = "session_start_time"
+        private const val KEY_UTM_SOURCE = "utm_source"
+        private const val KEY_UTM_MEDIUM = "utm_medium"
+        private const val KEY_UTM_CAMPAIGN = "utm_campaign"
+        private const val KEY_UTM_TERM = "utm_term"
+        private const val KEY_UTM_CONTENT = "utm_content"
+
+        @Volatile
+        private var instance: SessionManager? = null
+
+        /**
+         * Initialize the SessionManager singleton
+         *
+         * Must be called once during SDK initialization.
+         *
+         * @param storage Key-value storage for persistence
+         */
+        fun initialize(storage: KeyValueStore) {
+            if (instance == null) {
+                synchronized(this) {
+                    if (instance == null) {
+                        instance = SessionManager(storage)
+                    }
+                }
+            }
+        }
+
+        /**
+         * Get the SessionManager instance
+         *
+         * @return The singleton instance
+         * @throws IllegalStateException if not initialized
+         */
+        fun getInstance(): SessionManager {
+            return instance ?: throw IllegalStateException(
+                "SessionManager not initialized. Call SessionManager.initialize() first."
+            )
+        }
+
+        // Static accessors for tracking counters
+        fun getSessionId(): String = getInstance().sessionId
+        fun getSessionStartTime(): String = getInstance().sessionStartTime
+        fun getScreenViewCount(): Int = getInstance().screenViewCounter.get()
+        fun getAdRequestCount(): Int = getInstance().adRequestCounter.get()
+        fun getAdImpressionCount(): Int = getInstance().adImpressionCounter.get()
+        fun getTotalRevenueMicros(): Long = getInstance().totalRevenueMicrosCounter.get()
+
+        fun incrementScreenViewCount() {
+            getInstance().screenViewCounter.incrementAndGet()
+        }
+
+        fun incrementAdRequestCount() {
+            getInstance().adRequestCounter.incrementAndGet()
+        }
+
+        fun incrementAdImpressionCount() {
+            getInstance().adImpressionCounter.incrementAndGet()
+        }
+
+        fun addRevenueMicros(micros: Long) {
+            getInstance().totalRevenueMicrosCounter.addAndGet(micros)
+        }
+
+        fun startNewSession() {
+            getInstance().resetSessionCounters()
+        }
+
+        /**
+         * Reset the singleton instance (for testing only)
+         */
+        internal fun resetForTesting() {
+            synchronized(this) {
+                instance?.resetState()
+                instance = null
+            }
+        }
+    }
+
+    // MARK: - Properties
+
+    /** Persistent user ID (stored across app launches) */
+    val userId: String
+
+    /** Current session ID (new per app launch) */
+    val sessionId: String
+
+    /** Session start time (ISO 8601 string) */
+    val sessionStartTime: String
+
+    /** Total number of sessions for this user (across all time) */
+    val totalSessionCount: Int
+
+    /** True if this is the user's first session */
+    val isNewUser: Boolean
+        get() = totalSessionCount == 1
+
+    /** UTM parameters (from deep links or attribution) */
+    var utmSource: String? = null
+        private set
+    var utmMedium: String? = null
+        private set
+    var utmCampaign: String? = null
+        private set
+    var utmTerm: String? = null
+        private set
+    var utmContent: String? = null
+        private set
+
+    /** Session attribution source (derived from UTM or defaults to "direct") */
+    val sessionSource: String
+        get() = utmSource ?: "direct"
+
+    /** Session attribution medium (derived from UTM or defaults to "none") */
+    val sessionMedium: String
+        get() = utmMedium ?: "none"
+
+    /** Number of page views in current session */
+    private val sessionDepthCounter = AtomicInteger(0)
+    val sessionDepth: Int
+        get() = sessionDepthCounter.get()
+
+    /** Current page ID (new per page/screen view) */
+    private val currentPageIdRef = AtomicReference<String?>(null)
+    val currentPageId: String?
+        get() = currentPageIdRef.get()
+
+    /** Current screen name (for use in impression events) */
+    private val currentScreenNameRef = AtomicReference<String?>(null)
+    val currentScreenName: String?
+        get() = currentScreenNameRef.get()
+
+    // Analytics tracking counters
+    internal val screenViewCounter = AtomicInteger(0)
+    internal val adRequestCounter = AtomicInteger(0)
+    internal val adImpressionCounter = AtomicInteger(0)
+    internal val totalRevenueMicrosCounter = AtomicLong(0)
+
+    init {
+        // Load or generate user_id
+        val existingUserId = storage.getString(KEY_USER_ID)
+        if (existingUserId != null) {
+            userId = existingUserId
+            BCLogger.d(TAG, "Loaded existing user_id: $existingUserId")
+        } else {
+            val newUserId = UUID.randomUUID().toString()
+            storage.putString(KEY_USER_ID, newUserId)
+            userId = newUserId
+            BCLogger.d(TAG, "Generated new user_id: $newUserId")
+        }
+
+        // Load session count and increment
+        val sessionCountStr = storage.getString(KEY_SESSION_COUNT) ?: "0"
+        val previousCount = sessionCountStr.toIntOrNull() ?: 0
+        totalSessionCount = previousCount + 1
+        storage.putString(KEY_SESSION_COUNT, totalSessionCount.toString())
+
+        // Generate new session_id for this app launch
+        sessionId = UUID.randomUUID().toString()
+
+        // Set session start time (ISO 8601 format)
+        sessionStartTime = getCurrentTimestamp()
+        storage.putString(KEY_SESSION_START_TIME, sessionStartTime)
+
+        // Load UTM parameters (if set from deep link)
+        utmSource = storage.getString(KEY_UTM_SOURCE)
+        utmMedium = storage.getString(KEY_UTM_MEDIUM)
+        utmCampaign = storage.getString(KEY_UTM_CAMPAIGN)
+        utmTerm = storage.getString(KEY_UTM_TERM)
+        utmContent = storage.getString(KEY_UTM_CONTENT)
+
+        BCLogger.d(TAG, "Started session $totalSessionCount with session_id: $sessionId")
+    }
+
+    // MARK: - Page Tracking
+
+    /**
+     * Start a new page view
+     *
+     * Generates a new page_id and increments session_depth.
+     * Should be called at the start of each screen/page view.
+     *
+     * @param screenName Optional screen name to store for impression tracking
+     * @return The new page_id
+     */
+    fun startPageView(screenName: String? = null): String {
+        val depth = sessionDepthCounter.incrementAndGet()
+        val pageId = UUID.randomUUID().toString()
+        currentPageIdRef.set(pageId)
+        screenName?.let { currentScreenNameRef.set(it) }
+
+        BCLogger.d(TAG, "Started page view $depth with page_id: $pageId, screenName: $screenName")
+
+        return pageId
+    }
+
+    /**
+     * Get the current page ID, generating one if needed
+     *
+     * @return The current page_id (creates one if none exists)
+     */
+    fun getOrCreatePageId(): String {
+        var pageId = currentPageIdRef.get()
+        if (pageId == null) {
+            // Auto-generate if no page view has been started
+            sessionDepthCounter.incrementAndGet()
+            pageId = UUID.randomUUID().toString()
+            currentPageIdRef.set(pageId)
+        }
+        return pageId
+    }
+
+    // MARK: - Reset
+
+    /** Reset session counters (when starting a new session) */
+    internal fun resetSessionCounters() {
+        screenViewCounter.set(0)
+        adRequestCounter.set(0)
+        adImpressionCounter.set(0)
+        totalRevenueMicrosCounter.set(0)
+        sessionDepthCounter.set(0)
+        currentPageIdRef.set(null)
+        BCLogger.d(TAG, "Session counters reset")
+    }
+
+    /** Reset all session state (for testing only) */
+    private fun resetState() {
+        storage.clear()
+        sessionDepthCounter.set(0)
+        currentPageIdRef.set(null)
+        resetSessionCounters()
+    }
+
+    // MARK: - UTM Parameter Management
+
+    /**
+     * Set UTM parameters (typically from deep link)
+     *
+     * This persists UTM parameters for attribution tracking. These will be
+     * loaded for future sessions until cleared.
+     *
+     * @param source UTM source (e.g., "google", "facebook")
+     * @param medium UTM medium (e.g., "cpc", "email")
+     * @param campaign UTM campaign (e.g., "summer_sale")
+     * @param term UTM term (optional keyword)
+     * @param content UTM content (optional content variant)
+     */
+    fun setUTMParameters(
+        source: String? = null,
+        medium: String? = null,
+        campaign: String? = null,
+        term: String? = null,
+        content: String? = null
+    ) {
+        utmSource = source
+        utmMedium = medium
+        utmCampaign = campaign
+        utmTerm = term
+        utmContent = content
+
+        // Persist to storage
+        source?.let { storage.putString(KEY_UTM_SOURCE, it) }
+        medium?.let { storage.putString(KEY_UTM_MEDIUM, it) }
+        campaign?.let { storage.putString(KEY_UTM_CAMPAIGN, it) }
+        term?.let { storage.putString(KEY_UTM_TERM, it) }
+        content?.let { storage.putString(KEY_UTM_CONTENT, it) }
+
+        BCLogger.d(TAG, "Set UTM parameters - source: $source, medium: $medium, campaign: $campaign")
+    }
+
+    /**
+     * Clear UTM parameters
+     */
+    fun clearUTMParameters() {
+        utmSource = null
+        utmMedium = null
+        utmCampaign = null
+        utmTerm = null
+        utmContent = null
+
+        storage.remove(KEY_UTM_SOURCE)
+        storage.remove(KEY_UTM_MEDIUM)
+        storage.remove(KEY_UTM_CAMPAIGN)
+        storage.remove(KEY_UTM_TERM)
+        storage.remove(KEY_UTM_CONTENT)
+    }
+
+    // MARK: - Timestamp Utilities
+
+    /**
+     * Get current timestamp in ISO 8601 format with milliseconds
+     *
+     * @return ISO 8601 timestamp string (e.g., "2025-01-15T10:30:00.000Z")
+     */
+    fun getCurrentTimestamp(): String {
+        val dateFormat = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+        dateFormat.timeZone = TimeZone.getTimeZone("UTC")
+        return dateFormat.format(Date())
+    }
+}

package/android/bigcrunch-ads/com/bigcrunch/ads/internal/DeviceHelper.kt

@@ -0,0 +1,60 @@
+package com.bigcrunch.ads.internal
+
+import android.content.Context
+import android.os.Build
+import android.provider.Settings
+import android.telephony.TelephonyManager
+import android.util.DisplayMetrics
+import com.bigcrunch.ads.models.DeviceData
+import java.util.*
+
+/**
+ * Helper class to get device information
+ */
+internal object DeviceHelper {
+
+    fun getDeviceData(context: Context): DeviceData {
+        val displayMetrics = context.resources.displayMetrics
+        val telephonyManager = context.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+
+        return DeviceData(
+            deviceId = getDeviceId(context),
+            deviceModel = "${Build.MANUFACTURER} ${Build.MODEL}",
+            osVersion = Build.VERSION.RELEASE,
+            appVersion = getAppVersion(context),
+            screenWidth = displayMetrics.widthPixels,
+            screenHeight = displayMetrics.heightPixels,
+            language = Locale.getDefault().language,
+            country = Locale.getDefault().country,
+            carrier = telephonyManager?.networkOperatorName,
+            networkType = getNetworkType(context),
+            isTablet = isTablet(context)
+        )
+    }
+
+    private fun getDeviceId(context: Context): String {
+        return Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID) ?: "unknown"
+    }
+
+    private fun getAppVersion(context: Context): String {
+        return try {
+            val packageInfo = context.packageManager.getPackageInfo(context.packageName, 0)
+            packageInfo.versionName ?: "unknown"
+        } catch (e: Exception) {
+            "unknown"
+        }
+    }
+
+    private fun getNetworkType(context: Context): String? {
+        // TODO: Implement network type detection
+        return "unknown"
+    }
+
+    private fun isTablet(context: Context): Boolean {
+        val displayMetrics = context.resources.displayMetrics
+        val widthDp = displayMetrics.widthPixels / displayMetrics.density
+        val heightDp = displayMetrics.heightPixels / displayMetrics.density
+        val screenSize = Math.sqrt((widthDp * widthDp + heightDp * heightDp).toDouble())
+        return screenSize >= 600
+    }
+}

package/android/bigcrunch-ads/com/bigcrunch/ads/internal/HttpClient.kt

@@ -0,0 +1,114 @@
+package com.bigcrunch.ads.internal
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import java.util.concurrent.TimeUnit
+
+/**
+ * HTTP client for making network requests
+ *
+ * Uses OkHttp for reliable networking with automatic retries and connection pooling.
+ * All methods are suspend functions that run on the IO dispatcher.
+ */
+internal class HttpClient {
+
+    private val client = OkHttpClient.Builder()
+        .connectTimeout(10, TimeUnit.SECONDS)
+        .readTimeout(10, TimeUnit.SECONDS)
+        .writeTimeout(10, TimeUnit.SECONDS)
+        .build()
+
+    /**
+     * Perform a GET request
+     *
+     * @param url The URL to fetch
+     * @param headers Optional HTTP headers
+     * @return Result containing response body or error
+     */
+    suspend fun get(
+        url: String,
+        headers: Map<String, String> = emptyMap()
+    ): Result<String> {
+        return withContext(Dispatchers.IO) {
+            try {
+                val requestBuilder = Request.Builder().url(url)
+
+                headers.forEach { (key, value) ->
+                    requestBuilder.addHeader(key, value)
+                }
+
+                val response = client.newCall(requestBuilder.build()).execute()
+
+                if (response.isSuccessful) {
+                    val body = response.body?.string() ?: ""
+                    BCLogger.v("HttpClient", "GET success: $url (${body.length} bytes)")
+                    Result.success(body)
+                } else {
+                    val error = "HTTP ${response.code}: ${response.message}"
+                    BCLogger.w("HttpClient", "GET failed: $url - $error")
+                    Result.failure(Exception(error))
+                }
+            } catch (e: Exception) {
+                BCLogger.e("HttpClient", "GET request failed: $url", e)
+                Result.failure(e)
+            }
+        }
+    }
+
+    /**
+     * Perform a POST request
+     *
+     * @param url The URL to post to
+     * @param body Request body (JSON string)
+     * @param headers Optional HTTP headers
+     * @return Result containing response body or error
+     */
+    suspend fun post(
+        url: String,
+        body: String,
+        headers: Map<String, String> = emptyMap()
+    ): Result<String> {
+        return withContext(Dispatchers.IO) {
+            try {
+                // Log the request body for debugging
+                BCLogger.d("HttpClient", "POST to: $url")
+                BCLogger.d("HttpClient", "Request body: $body")
+
+                val mediaType = "application/json".toMediaType()
+                val requestBody = body.toRequestBody(mediaType)
+
+                val requestBuilder = Request.Builder()
+                    .url(url)
+                    .post(requestBody)
+
+                headers.forEach { (key, value) ->
+                    requestBuilder.addHeader(key, value)
+                }
+
+                val response = client.newCall(requestBuilder.build()).execute()
+
+                if (response.isSuccessful) {
+                    val responseBody = response.body?.string() ?: ""
+                    BCLogger.v("HttpClient", "POST success: $url")
+                    Result.success(responseBody)
+                } else {
+                    // Log response body for 4xx errors to see what the server says
+                    val errorBody = response.body?.string() ?: ""
+                    val error = "HTTP ${response.code}: ${response.message}"
+                    BCLogger.w("HttpClient", "POST failed: $url - $error")
+                    if (errorBody.isNotEmpty()) {
+                        BCLogger.w("HttpClient", "Error response body: $errorBody")
+                    }
+                    Result.failure(Exception(error))
+                }
+            } catch (e: Exception) {
+                BCLogger.e("HttpClient", "POST request failed: $url", e)
+                Result.failure(e)
+            }
+        }
+    }
+}

package/android/bigcrunch-ads/com/bigcrunch/ads/internal/Logger.kt

@@ -0,0 +1,71 @@
+package com.bigcrunch.ads.internal
+
+import android.util.Log
+
+/**
+ * Internal logger for BigCrunch Ads SDK
+ *
+ * All logs are prefixed with "BCrunch:" for easy filtering.
+ * Logging can be disabled in production by setting isEnabled = false.
+ * Error logs are always shown regardless of isEnabled flag.
+ */
+internal object BCLogger {
+
+    /**
+     * Enable/disable debug logging
+     * Defaults to false for production builds
+     */
+    var isEnabled = false
+
+    /**
+     * Verbose log - detailed debugging information
+     */
+    fun v(tag: String, msg: String) {
+        if (isEnabled) {
+            Log.v("BCrunch:$tag", msg)
+        }
+    }
+
+    /**
+     * Debug log - general debugging information
+     */
+    fun d(tag: String, msg: String) {
+        if (isEnabled) {
+            Log.d("BCrunch:$tag", msg)
+        }
+    }
+
+    /**
+     * Info log - informational messages
+     */
+    fun i(tag: String, msg: String) {
+        if (isEnabled) {
+            Log.i("BCrunch:$tag", msg)
+        }
+    }
+
+    /**
+     * Warning log - potential issues
+     */
+    fun w(tag: String, msg: String, throwable: Throwable? = null) {
+        if (isEnabled) {
+            if (throwable != null) {
+                Log.w("BCrunch:$tag", msg, throwable)
+            } else {
+                Log.w("BCrunch:$tag", msg)
+            }
+        }
+    }
+
+    /**
+     * Error log - critical errors
+     * Always logs regardless of isEnabled flag
+     */
+    fun e(tag: String, msg: String, throwable: Throwable? = null) {
+        if (throwable != null) {
+            Log.e("BCrunch:$tag", msg, throwable)
+        } else {
+            Log.e("BCrunch:$tag", msg)
+        }
+    }
+}

package/android/bigcrunch-ads/com/bigcrunch/ads/internal/PrivacyStore.kt

@@ -0,0 +1,125 @@
+package com.bigcrunch.ads.internal
+
+import android.content.Context
+import android.preference.PreferenceManager
+
+/**
+ * Centralized privacy signal store
+ *
+ * Manages GDPR, CCPA, and COPPA privacy signals for the SDK.
+ * Reads IAB TCF/USP standard keys from SharedPreferences when available,
+ * and provides structured objects for bid request construction.
+ */
+internal class PrivacyStore(private val context: Context) {
+
+    private val lock = Any()
+
+    // SDK-set values (from public API)
+    @Volatile private var _gdprConsentString: String? = null
+    @Volatile private var _gdprApplies: Boolean? = null
+    @Volatile private var _ccpaString: String? = null
+    @Volatile private var _coppaApplies: Boolean = false
+
+    companion object {
+        // IAB standard SharedPreferences keys
+        private const val IAB_TCF_CONSENT_KEY = "IABTCF_TCString"
+        private const val IAB_TCF_GDPR_APPLIES_KEY = "IABTCF_gdprApplies"
+        private const val IAB_USP_STRING_KEY = "IABUSPrivacy_String"
+    }
+
+    // MARK: - Setters (called from public API)
+
+    fun setGdprConsent(consent: String) {
+        synchronized(lock) {
+            _gdprApplies = true
+            _gdprConsentString = consent
+        }
+        BCLogger.d("PrivacyStore", "GDPR consent set")
+    }
+
+    fun setCcpaString(ccpa: String) {
+        synchronized(lock) {
+            _ccpaString = ccpa
+        }
+        // Also write to IAB standard key for CMP interop
+        PreferenceManager.getDefaultSharedPreferences(context)
+            .edit()
+            .putString(IAB_USP_STRING_KEY, ccpa)
+            .apply()
+        BCLogger.d("PrivacyStore", "CCPA string set")
+    }
+
+    fun setCoppaApplies(applies: Boolean) {
+        synchronized(lock) {
+            _coppaApplies = applies
+        }
+        BCLogger.d("PrivacyStore", "COPPA set to $applies")
+    }
+
+    // MARK: - Getters
+
+    /** Effective GDPR consent string (SDK-set takes priority, then IAB TCF) */
+    val gdprConsentString: String?
+        get() = synchronized(lock) {
+            _gdprConsentString
+        } ?: iabPrefs.getString(IAB_TCF_CONSENT_KEY, null)
+
+    /** Whether GDPR applies (SDK-set takes priority, then IAB TCF) */
+    val gdprApplies: Boolean?
+        get() {
+            synchronized(lock) {
+                _gdprApplies?.let { return it }
+            }
+            val prefs = iabPrefs
+            return if (prefs.contains(IAB_TCF_GDPR_APPLIES_KEY)) {
+                prefs.getInt(IAB_TCF_GDPR_APPLIES_KEY, 0) == 1
+            } else {
+                null
+            }
+        }
+
+    /** Effective CCPA/USP string (SDK-set takes priority, then IAB USP) */
+    val ccpaString: String?
+        get() = synchronized(lock) {
+            _ccpaString
+        } ?: iabPrefs.getString(IAB_USP_STRING_KEY, null)
+
+    val coppaApplies: Boolean
+        get() = synchronized(lock) { _coppaApplies }
+
+    private val iabPrefs
+        get() = PreferenceManager.getDefaultSharedPreferences(context)
+
+    // MARK: - Bid Request Helpers
+
+    /** Build the `regs` object for an OpenRTB bid request */
+    fun buildRegsMap(): Map<String, Any> {
+        val regs = mutableMapOf<String, Any>()
+        val ext = mutableMapOf<String, Any>()
+
+        regs["coppa"] = if (coppaApplies) 1 else 0
+
+        gdprApplies?.let { ext["gdpr"] = if (it) 1 else 0 }
+        ccpaString?.let { ext["us_privacy"] = it }
+
+        if (ext.isNotEmpty()) {
+            regs["ext"] = ext
+        }
+
+        return regs
+    }
+
+    /** Build the `user` object for an OpenRTB bid request */
+    fun buildUserMap(): Map<String, Any> {
+        val user = mutableMapOf<String, Any>()
+        val ext = mutableMapOf<String, Any>()
+
+        gdprConsentString?.let { ext["consent"] = it }
+
+        if (ext.isNotEmpty()) {
+            user["ext"] = ext
+        }
+
+        return user
+    }
+}