Add Pre launch module to report TTID on Cross Platform SDKs

Author: sbarrio

dd-sdk-android-internal/src/main/java/com/datadog/android/rum/AppLaunchPreInitCollector.kt

@@ -13,7 +13,6 @@ import android.os.Handler
 import android.os.Looper
 import android.os.Process
 import android.os.SystemClock
-import android.util.Log
 import androidx.annotation.VisibleForTesting
 import com.datadog.android.internal.system.BuildSdkVersionProvider
 import com.datadog.android.rum.startup.RumFirstDrawTimeReporter
@@ -46,6 +45,7 @@ import kotlin.time.Duration.Companion.seconds
  * [java.lang.ref.WeakReference] to an [android.app.Activity]. It is single-use per process: there
  * is no automatic reset for warm re-launches, as each process has exactly one cold-start lifetime.
  */
+@Suppress("PreferTimeProvider", "UnsafeThirdPartyFunctionCall")
 object AppLaunchPreInitCollector {
 
     /**
@@ -142,7 +142,7 @@ object AppLaunchPreInitCollector {
     // endregion
 
     private val firstFrameCallbacks = CopyOnWriteArrayList<(Long) -> Unit>()
-    private var _application: Application? = null
+    private var registeredApplication: Application? = null
 
     /** Private flag tracking whether any Activity has been destroyed (process is warm). */
     private var _isFirstActivityForProcess: Boolean = true
@@ -201,7 +201,6 @@ object AppLaunchPreInitCollector {
     private fun onBeforeActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
         // CAS: only the first caller transitions IDLE -> CAPTURING; concurrent claim() loses
         if (!_state.compareAndSet(State.IDLE, State.CAPTURING)) {
-            Log.d(TAG, "onBeforeActivityCreated: CAS failed — state is ${_state.get()}, not IDLE; skipping")
             return
         }
 
@@ -211,49 +210,33 @@ object AppLaunchPreInitCollector {
         isFirstActivityForProcess = _isFirstActivityForProcess
         processStartNs = computeProcessStartNs()
 
-        Log.d(
-            TAG,
-            "IDLE→CAPTURING: activity=${activity.javaClass.simpleName}" +
-                " hasSavedInstanceState=$hasSavedInstanceState" +
-                " isFirstActivityForProcess=$isFirstActivityForProcess" +
-                " processStartNs=$processStartNs" +
-                " activityOnCreateNs=$activityOnCreateNs" +
-                " gapMs=${(activityOnCreateNs - processStartNs) / 1_000_000}"
-        )
-
         // Unregister lifecycle callbacks — we've captured what we need from the first Activity
-        _application?.unregisterActivityLifecycleCallbacks(lifecycleCallbacks)
+        registeredApplication?.unregisterActivityLifecycleCallbacks(lifecycleCallbacks)
 
         // Subscribe to first frame drawn — transitions CAPTURING -> COMPLETE
         val handler = handlerFactory()
         val reporter = firstDrawTimeReporterFactory(handler)
-        reporter.subscribeToFirstFrameDrawn(activity, object : RumFirstDrawTimeReporter.Callback {
-            override fun onFirstFrameDrawn(timestampNs: Long) {
-                firstFrameNs = timestampNs
-                _state.compareAndSet(State.CAPTURING, State.COMPLETE)
-
-                Log.d(
-                    TAG,
-                    "CAPTURING->COMPLETE: first frame drawn" +
-                        " firstFrameNs=$firstFrameNs" +
-                        " ttidMs=${(firstFrameNs - activityOnCreateNs) / 1_000_000}" +
-                        " totalMs=${(firstFrameNs - processStartNs) / 1_000_000}" +
-                        " pendingCallbacks=${firstFrameCallbacks.size}"
-                )
-
-                // Drain all enqueued callbacks
-                val callbacks = firstFrameCallbacks.toList()
-                firstFrameCallbacks.clear()
-                callbacks.forEach { cb -> cb(firstFrameNs) }
+        reporter.subscribeToFirstFrameDrawn(
+            activity,
+            object : RumFirstDrawTimeReporter.Callback {
+                override fun onFirstFrameDrawn(timestampNs: Long) {
+                    firstFrameNs = timestampNs
+                    _state.compareAndSet(State.CAPTURING, State.COMPLETE)
+
+                    // Drain all enqueued callbacks
+                    val callbacks = firstFrameCallbacks.toList()
+                    firstFrameCallbacks.clear()
+                    callbacks.forEach { cb -> cb(firstFrameNs) }
+                }
             }
-        })
+        )
     }
 
     /**
      * Compute the process start time in nanoseconds.
      *
      * On API 24+, uses Process.getStartElapsedRealtime() to back-compute from the current
-     * elapsed realtime clock. Applies a two-direction OEM sanity check:
+     * elapsed realtime clock. Applies a two-direction OEM coherence check:
      * - If computed time is after DdRumContentProvider.createTimeNs (impossible), fall back.
      * - If computed time is more than 10s before createTimeNs (unreasonable), fall back.
      *
@@ -294,12 +277,10 @@ object AppLaunchPreInitCollector {
      */
     fun install(application: Application) {
         if (!_state.compareAndSet(State.NOT_INSTALLED, State.IDLE)) {
-            Log.d(TAG, "install() called but already in state ${_state.get()}, skipping")
             return
         }
-        _application = application
+        registeredApplication = application
         application.registerActivityLifecycleCallbacks(lifecycleCallbacks)
-        Log.d(TAG, "Installed — state: IDLE, ActivityLifecycleCallbacks registered")
     }
 
     /**
@@ -318,10 +299,7 @@ object AppLaunchPreInitCollector {
     fun claim(): Boolean {
         val success = _state.compareAndSet(State.IDLE, State.CLAIMED)
         if (success) {
-            _application?.unregisterActivityLifecycleCallbacks(lifecycleCallbacks)
-            Log.d(TAG, "Claimed — SDK initialized before first Activity (IDLE→CLAIMED); callbacks unregistered")
-        } else {
-            Log.d(TAG, "claim() CAS failed — state is ${_state.get()}, not IDLE; collector already in use")
+            registeredApplication?.unregisterActivityLifecycleCallbacks(lifecycleCallbacks)
         }
         return success
     }
@@ -342,30 +320,24 @@ object AppLaunchPreInitCollector {
      */
     fun addFirstFrameCallback(cb: (Long) -> Unit) {
         if (_state.get() == State.COMPLETE) {
-            Log.d(TAG, "addFirstFrameCallback: already COMPLETE, invoking callback synchronously")
             cb(firstFrameNs)
             return
         }
         firstFrameCallbacks.add(cb)
         // Double-check: state may have transitioned to COMPLETE between the first check and the add
         if (_state.get() == State.COMPLETE) {
             if (firstFrameCallbacks.remove(cb)) {
-                Log.d(TAG, "addFirstFrameCallback: TOCTOU race — COMPLETE during enqueue, invoking synchronously")
                 cb(firstFrameNs)
             }
-        } else {
-            Log.d(TAG, "addFirstFrameCallback: state=${_state.get()}, callback enqueued (${firstFrameCallbacks.size} total)")
         }
     }
 
     // endregion
 
     // region Constants
 
-    internal const val TAG = "DD/AppLaunch"
-
     /**
-     * Threshold for the two-direction OEM clock sanity check.
+     * Threshold for the two-direction OEM clock coherence check.
      * If computed process start time is more than 10s before DdRumContentProvider.createTimeNs,
      * it is considered an OEM bug and createTimeNs is used as fallback.
      */
@@ -392,7 +364,7 @@ object AppLaunchPreInitCollector {
         _isFirstActivityForProcess = true
         activity = null
         firstFrameCallbacks.clear()
-        _application = null
+        registeredApplication = null
         buildSdkVersionProvider = BuildSdkVersionProvider.DEFAULT
         handlerFactory = { Handler(Looper.getMainLooper()) }
         firstDrawTimeReporterFactory = { handler ->

dd-sdk-android-internal/src/main/java/com/datadog/android/rum/startup/RumFirstDrawTimeReporter.kt

@@ -8,10 +8,33 @@ package com.datadog.android.rum.startup
 
 import android.app.Activity
 
+/**
+ * Reports the timestamp of the first drawn frame for a given [Activity].
+ *
+ * Used by the RUM SDK to measure Time To Initial Display (TTID) by observing when the
+ * activity's window first renders its content on screen.
+ */
 interface RumFirstDrawTimeReporter {
+
+    /**
+     * Callback invoked when the first frame of an activity's window has been drawn.
+     */
     interface Callback {
+        /**
+         * Called once the first frame has been drawn.
+         *
+         * @param timestampNs The elapsed realtime timestamp of the first draw, in nanoseconds.
+         */
         fun onFirstFrameDrawn(timestampNs: Long)
     }
 
+    /**
+     * Subscribes to receive a callback when the first frame of [activity]'s window is drawn.
+     *
+     * The [callback] is guaranteed to be invoked at most once per subscription.
+     *
+     * @param activity The activity whose first frame draw should be observed.
+     * @param callback The callback to invoke when the first frame is drawn.
+     */
     fun subscribeToFirstFrameDrawn(activity: Activity, callback: Callback)
 }

dd-sdk-android-internal/src/main/java/com/datadog/android/rum/startup/RumFirstDrawTimeReporterImpl.kt

@@ -7,12 +7,23 @@
 package com.datadog.android.rum.startup
 
 import android.app.Activity
+import android.app.Application
+import android.os.Bundle
 import android.os.Handler
 import android.os.Message
 import android.util.Log
 import android.view.View
 import android.view.ViewTreeObserver
+import java.lang.ref.WeakReference
 
+/**
+ * Default implementation of [RumFirstDrawTimeReporter].
+ *
+ * Hooks into the activity's window via [ViewTreeObserver.OnDrawListener] to capture the first
+ * frame draw timestamp, handling both the case where the decor view is already attached and
+ * the case where it becomes available later via [WindowCallbacksRegistry].
+ */
+@Suppress("UnsafeThirdPartyFunctionCall")
 class RumFirstDrawTimeReporterImpl(
     private val timeProviderNs: () -> Long,
     private val windowCallbacksRegistry: WindowCallbacksRegistry,
@@ -38,6 +49,7 @@ class RumFirstDrawTimeReporterImpl(
                 }
             }
             windowCallbacksRegistry.addListener(activity, listener)
+            registerDestroyCleanup(activity, listener)
         } else {
             onDecorViewReady(activity, callback)
         }
@@ -107,6 +119,37 @@ class RumFirstDrawTimeReporterImpl(
         }
     }
 
+    // WindowCallbacksRegistryImpl stores Activity→WindowCallback in a WeakHashMap, but
+    // WindowCallback holds a strong reference back to the Activity via FixedWindowCallback.delegate
+    // (the Activity is its own Window.Callback). This circular reference prevents GC.
+    // When an Activity is destroyed before setContentView is called (e.g. an interstitial that
+    // just calls startActivity + finish), the listener never fires via onContentChanged, so the
+    // entry is never cleaned up. Registering a lifecycle callback to remove it on destroy breaks
+    // the strong reference and lets GC collect the Activity.
+    private fun registerDestroyCleanup(activity: Activity, listener: WindowCallbackListener) {
+        val application = activity.application ?: return
+        val weakActivity = WeakReference(activity)
+        // WeakReference so this callback (held by Application) does not itself keep the
+        // listener (and through it, the Activity) alive.
+        val weakListener = WeakReference(listener)
+        application.registerActivityLifecycleCallbacks(object : Application.ActivityLifecycleCallbacks {
+            override fun onActivityCreated(a: Activity, b: Bundle?) {}
+            override fun onActivityStarted(a: Activity) {}
+            override fun onActivityResumed(a: Activity) {}
+            override fun onActivityPaused(a: Activity) {}
+            override fun onActivityStopped(a: Activity) {}
+            override fun onActivitySaveInstanceState(a: Activity, b: Bundle) {}
+            override fun onActivityDestroyed(destroyed: Activity) {
+                if (destroyed === weakActivity.get()) {
+                    weakListener.get()?.let { l ->
+                        windowCallbacksRegistry.removeListener(destroyed, l)
+                    }
+                    application.unregisterActivityLifecycleCallbacks(this)
+                }
+            }
+        })
+    }
+
     private fun onFirstDraw(callback: RumFirstDrawTimeReporter.Callback) {
         val nowNs = timeProviderNs()
 

dd-sdk-android-internal/src/main/java/com/datadog/android/rum/startup/WindowCallbacksRegistry.kt

@@ -14,15 +14,50 @@ import java.util.WeakHashMap
 import kotlin.collections.getOrPut
 import kotlin.let
 
+/**
+ * Listener that is notified when the content of an activity's window changes.
+ *
+ * Used to detect when the decor view becomes available after [Activity.setContentView] is called.
+ */
 interface WindowCallbackListener {
+    /**
+     * Called when the window's content has changed (i.e., [Window.Callback.onContentChanged]).
+     */
     fun onContentChanged()
 }
 
+/**
+ * Manages [WindowCallbackListener] registrations on a per-[Activity] basis.
+ *
+ * Wraps the activity's [Window.Callback] so that content-change events can be forwarded to
+ * registered listeners without replacing any existing callback logic.
+ */
 interface WindowCallbacksRegistry {
+    /**
+     * Registers [listener] to receive content-change callbacks for [activity].
+     *
+     * @param activity The activity whose window callback should be observed.
+     * @param listener The listener to register.
+     */
     fun addListener(activity: Activity, listener: WindowCallbackListener)
+
+    /**
+     * Unregisters [listener] from content-change callbacks for [activity].
+     *
+     * If no more listeners remain for the activity, the wrapped window callback is removed.
+     *
+     * @param activity The activity whose window callback is being observed.
+     * @param listener The listener to unregister.
+     */
     fun removeListener(activity: Activity, listener: WindowCallbackListener)
 }
 
+/**
+ * Default implementation of [WindowCallbacksRegistry].
+ *
+ * Maintains a weak mapping from [Activity] to a wrapped [Window.Callback] so that listeners
+ * can be added and removed without leaking activity references.
+ */
 class WindowCallbacksRegistryImpl : WindowCallbacksRegistry {
     private val callbacks = WeakHashMap<Activity, WindowCallback>()
 
@@ -62,6 +97,7 @@ class WindowCallbacksRegistryImpl : WindowCallbacksRegistry {
     }
 }
 
+@Suppress("PackageNameVisibility")
 private class WindowCallback(
     val wrapped: Window.Callback
 ) : FixedWindowCallback(wrapped) {