Merge pull request #3566 from DataDog/feature/heatmaps

Merge heatmaps into develop

Author: jonathanmos

dd-sdk-android-internal/api/apiSurface

@@ -1,3 +1,8 @@
+data class com.datadog.android.heatmaps.CrossPlatformHeatmapActionData
+  constructor(List<String>, String, Long, Long, Long?, Long?)
+interface com.datadog.android.heatmaps.HeatmapIdentifierRegistryProvider
+  val heatmapIdentifierRegistry: com.datadog.android.internal.heatmaps.HeatmapIdentifierRegistry
+fun heatmapViewKey(android.view.View): Long
 interface com.datadog.android.internal.attributes.LocalAttribute
   enum Key
     constructor(String)
@@ -60,6 +65,15 @@ class com.datadog.android.internal.data.SharedPreferencesStorage : PreferencesSt
   override fun clear()
 data class com.datadog.android.internal.flags.RumFlagEvaluationMessage
   constructor(String, Any)
+data class com.datadog.android.internal.heatmaps.HeatmapIdentifier
+  constructor(String)
+  companion object 
+    fun create(List<String>, String, String, (Throwable) -> Unit = {}): HeatmapIdentifier?
+interface com.datadog.android.internal.heatmaps.HeatmapIdentifierRegistry
+  fun setHeatmapIdentifiers(Map<Long, HeatmapIdentifier>, String)
+  fun getHeatmapIdentifier(Long, String): HeatmapIdentifier?
+  companion object 
+    fun create(): HeatmapIdentifierRegistry
 class com.datadog.android.internal.lifecycle.ProcessLifecycleMonitor : android.app.Application.ActivityLifecycleCallbacks
   constructor(Callback)
   val activitiesResumedCounter: java.util.concurrent.atomic.AtomicInteger
@@ -271,6 +285,7 @@ fun StringBuilder.appendIfNotEmpty(String)
 fun StringBuilder.appendIfNotEmpty(Char)
 fun String.toBase64(): String
 fun String.fromBase64(): String?
+fun android.view.View.isValidTapTarget(): Boolean
 fun Thread.safeGetThreadId(): Long
 fun Thread.State.asString(): String
 fun Array<StackTraceElement>.loggableStackTrace(): String

dd-sdk-android-internal/api/dd-sdk-android-internal.api

@@ -1,3 +1,32 @@
+public final class com/datadog/android/heatmaps/CrossPlatformHeatmapActionData {
+	public fun <init> (Ljava/util/List;Ljava/lang/String;JJLjava/lang/Long;Ljava/lang/Long;)V
+	public final fun component1 ()Ljava/util/List;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()J
+	public final fun component4 ()J
+	public final fun component5 ()Ljava/lang/Long;
+	public final fun component6 ()Ljava/lang/Long;
+	public final fun copy (Ljava/util/List;Ljava/lang/String;JJLjava/lang/Long;Ljava/lang/Long;)Lcom/datadog/android/heatmaps/CrossPlatformHeatmapActionData;
+	public static synthetic fun copy$default (Lcom/datadog/android/heatmaps/CrossPlatformHeatmapActionData;Ljava/util/List;Ljava/lang/String;JJLjava/lang/Long;Ljava/lang/Long;ILjava/lang/Object;)Lcom/datadog/android/heatmaps/CrossPlatformHeatmapActionData;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getElementPath ()Ljava/util/List;
+	public final fun getPositionX ()J
+	public final fun getPositionY ()J
+	public final fun getTargetHeight ()Ljava/lang/Long;
+	public final fun getTargetWidth ()Ljava/lang/Long;
+	public final fun getViewUrl ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public abstract interface class com/datadog/android/heatmaps/HeatmapIdentifierRegistryProvider {
+	public abstract fun getHeatmapIdentifierRegistry ()Lcom/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry;
+}
+
+public final class com/datadog/android/heatmaps/HeatmapViewKeyKt {
+	public static final fun heatmapViewKey (Landroid/view/View;)J
+}
+
 public abstract interface class com/datadog/android/internal/attributes/LocalAttribute {
 }
 
@@ -123,6 +152,39 @@ public final class com/datadog/android/internal/flags/RumFlagEvaluationMessage {
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class com/datadog/android/internal/heatmaps/HeatmapIdentifier {
+	public static final field Companion Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier$Companion;
+	public fun <init> (Ljava/lang/String;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+	public static synthetic fun copy$default (Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;Ljava/lang/String;ILjava/lang/Object;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getRawValue ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/datadog/android/internal/heatmaps/HeatmapIdentifier$Companion {
+	public final fun create (Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+	public static synthetic fun create$default (Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier$Companion;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+}
+
+public abstract interface class com/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry {
+	public static final field Companion Lcom/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry$Companion;
+	public abstract fun getHeatmapIdentifier (JLjava/lang/String;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+	public abstract fun setHeatmapIdentifiers (Ljava/util/Map;Ljava/lang/String;)V
+}
+
+public final class com/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry$Companion {
+	public final fun create ()Lcom/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry;
+}
+
+public final class com/datadog/android/internal/heatmaps/NoOpHeatmapIdentifierRegistry : com/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry {
+	public fun <init> ()V
+	public fun getHeatmapIdentifier (JLjava/lang/String;)Lcom/datadog/android/internal/heatmaps/HeatmapIdentifier;
+	public fun setHeatmapIdentifiers (Ljava/util/Map;Ljava/lang/String;)V
+}
+
 public final class com/datadog/android/internal/lifecycle/ProcessLifecycleMonitor : android/app/Application$ActivityLifecycleCallbacks {
 	public fun <init> (Lcom/datadog/android/internal/lifecycle/ProcessLifecycleMonitor$Callback;)V
 	public final fun getActivitiesResumedCounter ()Ljava/util/concurrent/atomic/AtomicInteger;
@@ -608,6 +670,10 @@ public final class com/datadog/android/internal/utils/StringExtKt {
 	public static final fun toBase64 (Ljava/lang/String;)Ljava/lang/String;
 }
 
+public final class com/datadog/android/internal/utils/TapTargetUtilsKt {
+	public static final fun isValidTapTarget (Landroid/view/View;)Z
+}
+
 public final class com/datadog/android/internal/utils/ThreadExtKt {
 	public static final fun asString (Ljava/lang/Thread$State;)Ljava/lang/String;
 	public static final fun loggableStackTrace ([Ljava/lang/StackTraceElement;)Ljava/lang/String;

dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/CrossPlatformHeatmapActionData.kt

@@ -0,0 +1,29 @@
+/*
+ * 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.android.heatmaps
+
+/**
+ * Heatmap data for a RUM action, used by cross-platform SDKs to correlate a tap action with
+ * a specific UI element.
+ *
+ * @property elementPath the path segments from the root component down to the tapped element
+ *   (e.g. `["root", "container", "submitButton"]`), using the same naming convention as the
+ *   cross-platform Session Replay layer so that the resulting identifier matches the wireframe.
+ * @property viewUrl the RUM view URL returned by `_RumInternalProxy.getCurrentViewUrl()` at tap time.
+ * @property positionX the x-coordinate of the tap relative to the target element, in dp.
+ * @property positionY the y-coordinate of the tap relative to the target element, in dp.
+ * @property targetWidth the width of the tapped element, in dp, or null if unavailable.
+ * @property targetHeight the height of the tapped element, in dp, or null if unavailable.
+ */
+data class CrossPlatformHeatmapActionData(
+    val elementPath: List<String>,
+    val viewUrl: String,
+    val positionX: Long,
+    val positionY: Long,
+    val targetWidth: Long?,
+    val targetHeight: Long?
+)

dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/HeatmapIdentifierRegistryProvider.kt

@@ -0,0 +1,22 @@
+/*
+ * 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.android.heatmaps
+
+import com.datadog.android.internal.heatmaps.HeatmapIdentifierRegistry
+
+/**
+ * Implemented by SDK features that own a [HeatmapIdentifierRegistry], allowing peer features
+ * to obtain a typed reference via [com.datadog.android.api.feature.FeatureScope.unwrap].
+ */
+interface HeatmapIdentifierRegistryProvider {
+    /**
+     * The registry that maps view identity keys to their stable [HeatmapIdentifier]s for this
+     * feature's current screen. Session Replay writes identifiers into this registry during
+     * each traversal; the RUM layer reads from it when a tap action is sent.
+     */
+    val heatmapIdentifierRegistry: HeatmapIdentifierRegistry
+}

dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/HeatmapViewKey.kt

@@ -0,0 +1,30 @@
+/*
+ * 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.android.heatmaps
+
+import android.view.View
+
+// Polynomial coefficient — matches Java's standard hashCode convention.
+internal const val HEATMAP_VIEW_KEY_COEFFICIENT = 31L
+
+/**
+ * Returns the key used to store and look up a view's [HeatmapIdentifier] in a
+ * [HeatmapIdentifierRegistry].
+ *
+ * The key combines the identity hash of the view with the identity hash of its direct parent
+ * using a polynomial combination with coefficient 31 (the same coefficient used by Java's
+ * standard `hashCode` convention). This makes the combinator non-commutative: swapping the
+ * view and parent hashes produces a different key.
+ *
+ * Note: the returned value is an opaque 64-bit quantity and may be negative, since
+ * [System.identityHashCode] returns a signed [Int] that is sign-extended on widening to [Long].
+ * Callers must not assume the key is non-negative.
+ */
+fun heatmapViewKey(view: View): Long {
+    val parentHash = view.parent?.let { System.identityHashCode(it) } ?: 0
+    return HEATMAP_VIEW_KEY_COEFFICIENT * System.identityHashCode(view).toLong() + parentHash.toLong()
+}

dd-sdk-android-internal/src/main/java/com/datadog/android/internal/heatmaps/HeatmapIdentifier.kt

@@ -0,0 +1,92 @@
+/*
+ * 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.android.internal.heatmaps
+
+import com.datadog.android.internal.utils.toHexString
+import java.io.UnsupportedEncodingException
+import java.net.URLEncoder
+import java.security.MessageDigest
+import java.security.NoSuchAlgorithmException
+
+/**
+ * A stable, globally unique identifier for a UI element, used to correlate
+ * RUM tap actions with Session Replay wireframes for heatmap rendering.
+ *
+ * @property rawValue the hex-encoded SHA-256 hash string that uniquely identifies the element.
+ */
+data class HeatmapIdentifier(val rawValue: String) {
+
+    companion object {
+
+        private const val SEPARATOR = "/"
+
+        private const val SCREEN_NAMESPACE_VIEW_PREFIX = "view:"
+
+        /**
+         * Creates a [HeatmapIdentifier] for the given UI element by hashing its canonical path,
+         * or null if hashing fails.
+         *
+         * All string parameters must be **raw, unencoded** values — this function applies
+         * percent-encoding internally. Cross-platform SDKs must pass raw strings (e.g. the
+         * literal screen name returned by `getCurrentViewUrl()`, not a pre-encoded version)
+         * so that the identifier is always produced by the same Android encoding logic.
+         *
+         * @param elementPath the path segments from the root view down to this element,
+         *   where each segment identifies a view in the hierarchy (e.g. its resource entry name).
+         * @param screenName the current RUM view URL, used to scope identifiers to a screen.
+         *   The `view:` namespace prefix is applied internally — callers pass the raw URL
+         *   (e.g. `https://example.com/home`), not the prefixed form.
+         * @param appPackageName the application package name (e.g. `com.example.app`),
+         *   used to globally namespace identifiers across apps.
+         * @param onHashingFailure invoked with the caught exception if hashing fails.
+         */
+        fun create(
+            elementPath: List<String>,
+            screenName: String,
+            appPackageName: String,
+            onHashingFailure: (Throwable) -> Unit = {}
+        ): HeatmapIdentifier? {
+            return try {
+                val path = canonicalPath(elementPath, screenName, appPackageName)
+                HeatmapIdentifier(sha256Hex(path))
+            } catch (e: NoSuchAlgorithmException) {
+                // Unreachable on Android: SHA-256 is always available.
+                onHashingFailure(e)
+                null
+            } catch (e: UnsupportedEncodingException) {
+                // Thrown by URLEncoder.encode if UTF-8 is unavailable (unreachable on Android).
+                onHashingFailure(e)
+                null
+            }
+        }
+
+        private fun canonicalPath(
+            elementPath: List<String>,
+            screenName: String,
+            appPackageName: String
+        ): String = buildString {
+            append(escape(appPackageName))
+            append(SEPARATOR)
+            append(escape(SCREEN_NAMESPACE_VIEW_PREFIX + screenName))
+            for (segment in elementPath) {
+                append(SEPARATOR)
+                append(escape(segment))
+            }
+        }
+
+        @Suppress("UnsafeThirdPartyFunctionCall") // UnsupportedEncodingException caught in create()
+        private fun escape(input: String): String = URLEncoder.encode(input, "UTF-8")
+
+        @Suppress("UnsafeThirdPartyFunctionCall") // SHA-256 is always available on Android
+        private fun sha256Hex(input: String): String {
+            val digest = MessageDigest.getInstance("SHA-256")
+            // digest(ByteArray): input is non-null, DigestException not thrown on this overload.
+            @Suppress("UnsafeThirdPartyFunctionCall")
+            return digest.digest(input.toByteArray(Charsets.UTF_8)).toHexString()
+        }
+    }
+}

dd-sdk-android-internal/src/main/java/com/datadog/android/internal/heatmaps/HeatmapIdentifierRegistry.kt

@@ -0,0 +1,51 @@
+/*
+ * 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.android.internal.heatmaps
+
+import com.datadog.tools.annotation.NoOpImplementation
+
+/**
+ * Stores and retrieves [HeatmapIdentifier]s keyed by composite view identity key
+ * (see [heatmapViewKey]).
+ *
+ * Implementations must be thread-safe: the write side (Session Replay) may call
+ * [setHeatmapIdentifiers] from a background traversal thread while the read side (RUM) calls
+ * [getHeatmapIdentifier] from the main thread.
+ */
+@NoOpImplementation(publicNoOpImplementation = true)
+interface HeatmapIdentifierRegistry {
+
+    /**
+     * Replaces the current snapshot with [identifiers], scoped to [screenName].
+     *
+     * @param identifiers a map of view identity keys (see [heatmapViewKey]) to their
+     *   [HeatmapIdentifier]s. Keys must be computed with [heatmapViewKey] at the time the
+     *   snapshot is captured so they match the keys produced at lookup time.
+     * @param screenName the RUM view URL active when the snapshot was computed. Used to
+     *   guard against stale reads after screen navigation.
+     */
+    fun setHeatmapIdentifiers(identifiers: Map<Long, HeatmapIdentifier>, screenName: String)
+
+    /**
+     * Returns the [HeatmapIdentifier] for the view with the given [heatmapViewKey], or null if
+     * the view is unknown or if [currentScreenName] does not match the screen that produced the
+     * current snapshot (indicating the snapshot is stale).
+     *
+     * @param heatmapViewKey the composite identity key of the tapped view, as returned by [heatmapViewKey].
+     *   Must match the key used when populating [setHeatmapIdentifiers].
+     * @param currentScreenName the RUM view URL active at the time of the tap.
+     */
+    fun getHeatmapIdentifier(heatmapViewKey: Long, currentScreenName: String): HeatmapIdentifier?
+
+    companion object {
+
+        /**
+         * Creates a default [HeatmapIdentifierRegistry] backed by an in-memory snapshot store.
+         */
+        fun create(): HeatmapIdentifierRegistry = HeatmapIdentifierStore()
+    }
+}

dd-sdk-android-internal/src/main/java/com/datadog/android/internal/heatmaps/HeatmapIdentifierStore.kt

@@ -0,0 +1,49 @@
+/*
+ * 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.android.internal.heatmaps
+
+import java.util.concurrent.locks.ReentrantReadWriteLock
+import kotlin.concurrent.read
+import kotlin.concurrent.write
+
+/**
+ * Internal — construct via [HeatmapIdentifierRegistry.create].
+ *
+ * Writes (one per Session Replay traversal) atomically replace the entire snapshot so reads
+ * always see a complete, consistent map — never a partial update. Reads are non-blocking
+ * with respect to other reads.
+ *
+ * Note: there is no guarantee that a read sees the snapshot that was current at the exact
+ * moment of a tap. If SR writes a new snapshot between the tap and the RUM lookup, the read
+ * returns the newer snapshot. The screen name guard ensures a stale cross-screen snapshot
+ * returns null — the worst case is a missed tap, not a wrong one.
+ */
+internal class HeatmapIdentifierStore : HeatmapIdentifierRegistry {
+
+    private val lock = ReentrantReadWriteLock()
+
+    private var snapshotScreenName: String? = null
+    private val identifiers: MutableMap<Long, HeatmapIdentifier> = mutableMapOf()
+
+    // Contract: both `screenName` (write side) and `currentScreenName` (read side) must be the
+    // raw `rumContext.viewUrl` string without any normalization (no trailing slashes, no encoding).
+    // A mismatch — e.g. from different formatting — silently returns null on every lookup.
+
+    override fun setHeatmapIdentifiers(identifiers: Map<Long, HeatmapIdentifier>, screenName: String) {
+        lock.write {
+            this.snapshotScreenName = screenName
+            this.identifiers.clear()
+            this.identifiers.putAll(identifiers)
+        }
+    }
+
+    override fun getHeatmapIdentifier(heatmapViewKey: Long, currentScreenName: String): HeatmapIdentifier? {
+        return lock.read {
+            if (snapshotScreenName == currentScreenName) identifiers[heatmapViewKey] else null
+        }
+    }
+}