RUMS-5681: Add support for heatmaps

Author: jonathanmos

example/src/App.tsx

@@ -8,12 +8,18 @@ import TraceScreen from './screens/TraceScreen';
 import style from './screens/styles';
 import { navigationRef } from './NavigationRoot';
 import { DdRumReactNavigationTracking, NavigationTrackingOptions, ParamsTrackingPredicate, ViewNamePredicate, ViewTrackingPredicate } from '@datadog/mobile-react-navigation';
-import { DatadogProvider, TrackingConsent, DdFlags } from '@datadog/mobile-react-native'
+import { DatadogProvider, TrackingConsent, DdFlags, DdLogs, DdSdkReactNative } from '@datadog/mobile-react-native'
 import { DatadogOpenFeatureProvider } from '@datadog/mobile-react-native-openfeature';
+import {
+  ImagePrivacyLevel,
+  SessionReplay,
+  TextAndInputPrivacyLevel,
+  TouchPrivacyLevel,
+} from '@datadog/mobile-react-native-session-replay';
 import { OpenFeature, OpenFeatureProvider } from '@openfeature/react-sdk';
 import { Route } from "@react-navigation/native";
 import { NestedNavigator } from './screens/NestedNavigator/NestedNavigator';
-import { getDatadogConfig, onDatadogInitialization } from './ddUtils';
+import { getDatadogConfig } from './ddUtils';
 
 const Tab = createBottomTabNavigator();
 
@@ -69,7 +75,18 @@ const configuration = getDatadogConfig(TrackingConsent.GRANTED)
 // const configuration = new DatadogProviderConfiguration("fake_value", "fake_value");
 
 const handleDatadogInitialization = async () => {
-  onDatadogInitialization();
+  DdLogs.info('The RN Sdk was properly initialized')
+  DdSdkReactNative.setUserInfo({id: "1337", name: "Xavier", email: "xg@example.com", extraInfo: { type: "premium" } })
+  DdSdkReactNative.addAttributes({campaign: "ad-network"})
+
+  // Enable Session Replay.
+  await SessionReplay.enable({
+    replaySampleRate: 100,
+    textAndInputPrivacyLevel: TextAndInputPrivacyLevel.MASK_SENSITIVE_INPUTS,
+    imagePrivacyLevel: ImagePrivacyLevel.MASK_NONE,
+    touchPrivacyLevel: TouchPrivacyLevel.SHOW,
+    enableHeatmaps: true,
+  });
 
   // Enable Datadog Flags feature.
   await DdFlags.enable();

example/src/ddUtils.tsx

@@ -57,12 +57,6 @@ export function getDatadogConfig(trackingConsent: TrackingConsent) {
     return config
 }
 
- export function onDatadogInitialization() {
-    DdLogs.info('The RN Sdk was properly initialized')
-    DdSdkReactNative.setUserInfo({id: "1337", name: "Xavier", email: "xg@example.com", extraInfo: { type: "premium" } })
-    DdSdkReactNative.addAttributes({campaign: "ad-network"})
-}
-
 // Legacy SDK Setup
 export function initializeDatadog(trackingConsent: TrackingConsent) {
 

packages/core/android/src/main/kotlin/com/datadog/reactnative/DdRumImplementation.kt

@@ -6,12 +6,15 @@
 
 package com.datadog.reactnative
 
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
 import com.datadog.android.rum.RumActionType
 import com.datadog.android.rum.RumAttributes
 import com.datadog.android.rum.RumErrorSource
 import com.datadog.android.rum.RumResourceKind
 import com.datadog.android.rum.RumResourceMethod
+import com.datadog.android.rum._RumInternalProxy
 import com.datadog.android.rum.featureoperations.FailureReason
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReadableArray
@@ -22,7 +25,13 @@ import java.util.Locale
  * The entry point to use Datadog's RUM feature.
  */
 @Suppress("TooManyFunctions")
-class DdRumImplementation(private val datadog: DatadogWrapper = DatadogSDKWrapper()) {
+class DdRumImplementation internal constructor(
+    private val datadog: DatadogWrapper = DatadogSDKWrapper(),
+    private val heatmapTouchResolver: HeatmapTouchResolver = HeatmapTouchResolver(),
+    private val mainThreadExecutor: (() -> Unit) -> Unit = { action ->
+        Handler(Looper.getMainLooper()).post(action)
+    }
+) {
     /**
      * Start tracking a RUM View.
      * @param key The view unique key identifier.
@@ -62,6 +71,16 @@ class DdRumImplementation(private val datadog: DatadogWrapper = DatadogSDKWrappe
             key = key,
             attributes = attributes
         )
+        // KNOWN GAP (dd-sdk-android): Session Replay only emits a ViewEnd record for a view when
+        // a later snapshot's RUM context resolves to a *different* view. The last view of any SR
+        // session (heatmap or otherwise) never gets a ViewEnd, because SessionReplayFeature.onStop()
+        // clears the recording queue instead of flushing a final ViewEnd for it, and there is no
+        // "next" snapshot to diff against. This can't be fixed from the RN wrapper — forcing a
+        // redraw here does not help: a snapshot taken with no active RUM view is dropped before
+        // reaching the diff logic (RumContextDataHandler returns null for an invalid RUM context),
+        // so it produces no ViewEnd, just a wasted draw and a spurious internal error log. Fixing
+        // this requires dd-sdk-android itself to flush a synthetic ViewEnd for the previous RUM
+        // context when recording stops.
         promise.resolve(null)
     }
 
@@ -117,14 +136,21 @@ class DdRumImplementation(private val datadog: DatadogWrapper = DatadogSDKWrappe
 
     /**
      * Add a RUM Action.
+     *
+     * When heatmaps are enabled and this is a TAP action with touch data, the current view URL is
+     * read synchronously (before any async view transition can change it), and `touch`'s fields
+     * are extracted defensively: `touch` is built on the JS side from a caller-supplied gesture
+     * event whose fields aren't guaranteed to be present, since `addAction`'s action context is
+     * public API. If any of these lookups fail, this falls back to a plain action — heatmaps are
+     * checked first since that's the cheapest condition and most likely to be false, short-
+     * circuiting the rest for the common non-heatmap session.
      * @param type The action type (tap, scroll, swipe, click, custom).
      * @param name The action name.
      * @param touch The native touch data for tap actions, or null for other action types.
-     * Currently unused on Android; reserved for heatmap support.
      * @param context The additional context to send.
      * @param timestampMs The timestamp when the action occurred (in milliseconds). If not provided, current timestamp will be used.
      */
-    @Suppress("LongParameterList", "UnusedParameter")
+    @Suppress("LongParameterList")
     fun addAction(
         type: String,
         name: String,
@@ -136,12 +162,68 @@ class DdRumImplementation(private val datadog: DatadogWrapper = DatadogSDKWrappe
         val attributes = context.toHashMap().toMutableMap().apply {
             put(RumAttributes.INTERNAL_TIMESTAMP, timestampMs.toLong())
         }
+
+        val eligibleAction = resolveHeatmapEligibility(type, touch)
+        if (eligibleAction == null) {
+            plainAddAction(type, name, attributes)
+            promise.resolve(null)
+            return
+        }
+
+        // Promise is resolved before dispatching to main thread, matching the iOS pattern.
+        promise.resolve(null)
+
+        mainThreadExecutor {
+            val heatmapData = heatmapTouchResolver.resolve(
+                eligibleAction.reactTag,
+                eligibleAction.positionX,
+                eligibleAction.positionY,
+                eligibleAction.viewUrl
+            )
+            if (heatmapData != null) {
+                eligibleAction.internalProxy.addActionWithHeatmap(
+                    type = type.asRumActionType(),
+                    name = name,
+                    crossPlatformHeatmapActionData = heatmapData,
+                    attributes = attributes
+                )
+            } else {
+                plainAddAction(type, name, attributes)
+            }
+        }
+    }
+
+    private data class HeatmapEligibleAction(
+        val internalProxy: _RumInternalProxy,
+        val viewUrl: String,
+        val reactTag: Int,
+        val positionX: Long,
+        val positionY: Long
+    )
+
+    private fun resolveHeatmapEligibility(type: String, touch: ReadableMap?): HeatmapEligibleAction? {
+        if (!heatmapsEnabled || touch == null || !type.equals("tap", ignoreCase = true)) {
+            return null
+        }
+
+        val internalProxy = datadog.getRumMonitor()._getInternal()
+        val viewUrl = internalProxy?.getCurrentViewUrl()
+        val touchFields = touch.toTouchFieldsOrNull()
+
+        return if (internalProxy != null && viewUrl != null && touchFields != null) {
+            val (reactTag, positionX, positionY) = touchFields
+            HeatmapEligibleAction(internalProxy, viewUrl, reactTag, positionX, positionY)
+        } else {
+            null
+        }
+    }
+
+    private fun plainAddAction(type: String, name: String, attributes: Map<String, Any?>) {
         datadog.getRumMonitor().addAction(
             type = type.asRumActionType(),
             name = name,
             attributes = attributes
         )
-        promise.resolve(null)
     }
 
     /**
@@ -459,10 +541,33 @@ class DdRumImplementation(private val datadog: DatadogWrapper = DatadogSDKWrappe
         }
     }
 
+    private fun ReadableMap.toTouchFieldsOrNull(): Triple<Int, Long, Long>? {
+        if (!hasKey("reactTag") || !hasKey("x") || !hasKey("y")) return null
+        return runCatching {
+            Triple(getInt("reactTag"), getDouble("x").toLong(), getDouble("y").toLong())
+        }.getOrNull()
+    }
+
     // endregion
+
     @Suppress("UndocumentedPublicClass")
     companion object {
         private const val MISSING_RESOURCE_SIZE = -1L
         internal const val NAME = "DdRum"
+
+        /**
+         * Whether heatmap data should be attached to TAP actions.
+         */
+        @Volatile
+        var heatmapsEnabled: Boolean = false
+            private set
+
+        /**
+         * Sets whether heatmap data should be attached to TAP actions. Called exclusively by
+         * [com.datadog.reactnative.sessionreplay.DdSessionReplayImplementation.enable].
+         */
+        fun setHeatmapsEnabled(enabled: Boolean) {
+            heatmapsEnabled = enabled
+        }
     }
 }

packages/core/android/src/main/kotlin/com/datadog/reactnative/HeatmapTouchResolver.kt

@@ -0,0 +1,113 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+package com.datadog.reactnative
+
+import android.content.res.Resources
+import android.view.View
+import android.view.ViewGroup
+import com.datadog.android.heatmaps.CrossPlatformHeatmapActionData
+
+/**
+ * Resolves a React Native touch event into a [CrossPlatformHeatmapActionData] by walking the
+ * Android view hierarchy to find the nearest valid tap-target ancestor, building the element path,
+ * and packaging the result for [com.datadog.android.rum._RumInternalProxy.addActionWithHeatmap].
+ */
+internal class HeatmapTouchResolver(
+    private val viewResolver: (Int) -> View? = { null }
+) {
+
+    /**
+     * Returns [CrossPlatformHeatmapActionData] for the given tap, or null if no valid tap-target
+     * ancestor could be found (in which case the caller should fall back to a plain addAction).
+     *
+     * The tap target is the nearest clickable-and-visible ancestor of the touched view: Session
+     * Replay's `HeatmapIdentifierResolver` only assigns a `permanentId` to such views, so an inner
+     * non-clickable child would produce a path that never matches an SR wireframe. The element
+     * path is built root-first using the same path-component convention as that resolver, so the
+     * resulting SHA-256 identifier matches the `permanentId` assigned to the SR wireframe.
+     */
+    fun resolve(
+        reactTag: Int,
+        positionX: Long,
+        positionY: Long,
+        viewUrl: String
+    ): CrossPlatformHeatmapActionData? = runCatching {
+        val view = viewResolver(reactTag)?.let { clickableVisibleAncestorOf(it) }
+        val elementPath = view?.let { elementPathFromRootTo(it) }
+
+        if (view != null && !elementPath.isNullOrEmpty()) {
+            val density = view.resources?.displayMetrics?.density ?: 1f
+            val targetWidth = (view.width / density).toLong().takeIf { it > 0 }
+            val targetHeight = (view.height / density).toLong().takeIf { it > 0 }
+
+            CrossPlatformHeatmapActionData(
+                elementPath = elementPath,
+                viewUrl = viewUrl,
+                positionX = positionX,
+                positionY = positionY,
+                targetWidth = targetWidth,
+                targetHeight = targetHeight
+            )
+        } else {
+            null
+        }
+    }.getOrNull()
+
+    // region Private helpers
+
+    private fun clickableVisibleAncestorOf(view: View): View? {
+        var current: View? = view
+        while (current != null) {
+            if (current.isClickable && current.visibility == View.VISIBLE) {
+                return current
+            }
+            current = current.parent as? View
+        }
+        return null
+    }
+
+    private fun elementPathFromRootTo(view: View): List<String> {
+        val path = mutableListOf<String>()
+        var current: View? = view
+        while (current != null) {
+            val parent = current.parent as? ViewGroup
+            val typeIndex = if (parent != null) computeTypeIndex(current, parent) else 0
+            path.add(pathComponentFor(current, typeIndex))
+            current = parent
+        }
+        path.reverse()
+        return path
+    }
+
+    private fun computeTypeIndex(view: View, parent: ViewGroup): Int {
+        val cls = view.javaClass
+        var index = 0
+        for (i in 0 until parent.childCount) {
+            val child = parent.getChildAt(i) ?: continue
+            if (child === view) break
+            if (child.javaClass === cls) index++
+        }
+        return index
+    }
+
+    private fun pathComponentFor(view: View, typeIndex: Int): String {
+        val viewId = view.id
+        if (viewId != View.NO_ID) {
+            try {
+                @Suppress("UnsafeThirdPartyFunctionCall")
+                val name = view.resources?.getResourceName(viewId)
+                if (!name.isNullOrEmpty()) {
+                    return "$name#$typeIndex"
+                }
+            } catch (_: Resources.NotFoundException) {
+            }
+        }
+        return "cls:${view.javaClass.name}#$typeIndex"
+    }
+
+    // endregion
+}

packages/core/android/src/newarch/kotlin/com/datadog/reactnative/DdRum.kt

@@ -12,6 +12,8 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.common.ViewUtil
 
 /**
  * The entry point to use Datadog's RUM feature.
@@ -22,7 +24,18 @@ class DdRum(
     datadogWrapper: DatadogWrapper = DatadogSDKWrapper()
 ) : NativeDdRumSpec(reactContext) {
 
-    private val implementation = DdRumImplementation(datadog = datadogWrapper)
+    private val implementation = DdRumImplementation(
+        datadog = datadogWrapper,
+        heatmapTouchResolver = HeatmapTouchResolver(viewResolver = { reactTag ->
+            try {
+                val uiManagerType = ViewUtil.getUIManagerType(reactTag)
+                UIManagerHelper.getUIManager(reactApplicationContext, uiManagerType)
+                    ?.resolveView(reactTag)
+            } catch (_: Exception) {
+                null
+            }
+        })
+    )
 
     override fun getName(): String = DdRumImplementation.NAME
 
@@ -105,7 +118,6 @@ class DdRum(
      * @param type The action type (tap, scroll, swipe, click, custom).
      * @param name The action name.
      * @param touch The native touch data for tap actions, or null for other action types.
-     * Currently unused on Android; reserved for heatmap support.
      * @param context The additional context to send.
      * @param timestampMs The timestamp when the action occurred (in milliseconds).
      * If not provided, current timestamp will be used.