[PANA-5681] Preparation for Heatmaps cross-platform integration

[jonathanmos]

What does this PR do?

Reorganise heatmap types into correct packages

Public declarations (CrossPlatformHeatmapActionData, HeatmapIdentifierRegistryProvider, heatmapViewKey) are moved out of com.datadog.android.internal.heatmaps, since public types must not live in a package named internal. isValidTapTarget was moved out of heatmaps since it is a general util.

HeatmapActionData is split into two distinct types:

NativeHeatmapActionData — carries a viewKey (a composite identity hash of the tapped View and its parent), used to look up a pre-computed identifier from the HeatmapIdentifierRegistry that Session Replay populated during its last traversal.
CrossPlatformHeatmapActionData — carries an elementPath (a list of string path segments) and viewUrl, from which the identifier is computed on demand at action-send time via HeatmapIdentifier.create().
HeatmapActionResolver and NativeHeatmapActionData are also moved from rum.internal.domain.scope (where they are not scope concepts) to the dedicated rum.internal.heatmaps package.

Add cross-platform heatmap tap action support

Exposes two new methods on _RumInternalProxy for cross-platform SDKs (React Native, etc.):

getCurrentViewUrl() — returns the URL of the currently active RUM view. Cross-platform SDKs must call this at tap time and use the result as both the screen name for Session Replay wireframe identifier computation and the viewUrl field of CrossPlatformHeatmapActionData.
addActionWithHeatmap() — records a tap action with heatmap data attached. The Android SDK validates that the view URL captured at tap time still matches the active view at action-send time, dropping the heatmap data (with a developer-facing warning) if navigation has occurred in between.

Motivation

Heatmaps on Android currently only work with native gesture tracking. This PR lays the foundation for cross-platform SDKs to emit heatmap-tagged tap actions, enabling heatmap features in React Native and future cross-platform targets.

Additional Notes

getCurrentViewUrl() reads from a volatile cached field updated after each RUM event, making it safe to call from the UI thread without blocking on the RUM executor.
The view URL mismatch guard in HeatmapActionResolver.CrossPlatform handles the inherent race between a tap on screen A and a navigation to screen B: if the view has changed by the time the action is processed, the heatmap data is dropped rather than attributed to the wrong screen.
Identifier computation for cross-platform actions uses the same HeatmapIdentifier.create() path as Session Replay, ensuring the resulting permanentId matches the wireframe identifier SR computed for the same element.

Review checklist (to be filled by reviewers)

• Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
• Make sure you discussed the feature or bugfix with the maintaining team in an Issue
• Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 72.27723% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.20%. Comparing base (aea05eb) to head (876979a).
⚠️ Report is 2 commits behind head on feature/heatmaps.

Files with missing lines	Patch %	Lines
...oid/rum/internal/heatmaps/HeatmapActionResolver.kt	79.07%	7 Missing and 2 partials ⚠️
...android/heatmaps/CrossPlatformHeatmapActionData.kt	0.00%	7 Missing ⚠️
...dog/android/internal/heatmaps/HeatmapIdentifier.kt	45.45%	6 Missing ⚠️
...ndroid/rum/internal/domain/scope/RumActionScope.kt	50.00%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@                 Coverage Diff                  @@
##           feature/heatmaps    #3549      +/-   ##
====================================================
+ Coverage             72.19%   72.20%   +0.01%     
====================================================
  Files                   970      972       +2     
  Lines                 35668    35751      +83     
  Branches               5937     5944       +7     
====================================================
+ Hits                  25748    25813      +65     
- Misses                 8289     8320      +31     
+ Partials               1631     1618      -13     

Files with missing lines	Coverage Δ
...ava/com/datadog/android/heatmaps/HeatmapViewKey.kt	100.00% <ø> (ø)
...m/datadog/android/internal/utils/TapTargetUtils.kt	100.00% <ø> (ø)
...rum/src/main/kotlin/com/datadog/android/rum/Rum.kt	86.42% <100.00%> (+0.17%)	⬆️
...otlin/com/datadog/android/rum/_RumInternalProxy.kt	68.00% <100.00%> (+2.78%)	⬆️
...lin/com/datadog/android/rum/internal/RumFeature.kt	92.81% <ø> (-0.23%)	⬇️
...g/android/rum/internal/domain/scope/RumRawEvent.kt	100.00% <100.00%> (ø)
...d/rum/internal/heatmaps/NativeHeatmapActionData.kt	100.00% <100.00%> (ø)
...entation/gestures/AndroidActionTrackingStrategy.kt	94.44% <ø> (ø)
...ernal/instrumentation/gestures/GesturesListener.kt	93.71% <100.00%> (ø)
.../android/rum/internal/monitor/DatadogRumMonitor.kt	87.64% <100.00%> (+0.46%)	⬆️
... and 7 more

... and 41 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6784792bdf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR prepares Android RUM + Session Replay for cross-platform Heatmaps by reorganizing Heatmap-related types into appropriate packages, splitting native vs cross-platform heatmap action payloads, and exposing cross-platform hooks via _RumInternalProxy.

Changes:

• Moved public Heatmap helpers/types out of com.datadog.android.internal.* into com.datadog.android.heatmaps and relocated isValidTapTarget into a general utils package.
• Introduced cross-platform heatmap action flow: _RumInternalProxy.getCurrentViewUrl() + _RumInternalProxy.addActionWithHeatmap(...), plus resolver logic to compute identifiers and drop stale heatmap data on view URL mismatch.
• Refactored native heatmap action handling into a dedicated HeatmapActionResolver and renamed the payload to NativeHeatmapActionData.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/recorder/SnapshotProducerHeatmapIdentifierTest.kt	Updates imports to new heatmapViewKey package.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/recorder/HeatmapIdentifierContractTest.kt	Updates imports to moved registry provider + view key helpers.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/LazyHeatmapIdentifierRegistryTest.kt	Updates imports to moved registry provider.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/recorder/SnapshotProducer.kt	Switches isValidTapTarget import to internal.utils.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/recorder/HeatmapIdentifierResolver.kt	Switches heatmapViewKey/isValidTapTarget imports and adjusts hashing-failure logging.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/LazyHeatmapIdentifierRegistry.kt	Uses moved HeatmapIdentifierRegistryProvider import and clarifies sentinel comments.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/utils/forge/NativeHeatmapActionDataForgeryFactory.kt	Updates forge factory to new NativeHeatmapActionData type/package.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/utils/forge/CrossPlatformHeatmapActionDataForgeryFactory.kt	Adds forgery factory for new cross-platform heatmap payload.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/utils/forge/Configurator.kt	Registers both native + cross-platform heatmap forgery factories.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/utils/config/GlobalRumMonitorTestConfiguration.kt	Updates test monitor stub to implement new heatmap methods.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/RumTest.kt	Ensures app package name is passed into the monitor and asserted in tests.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/RumInternalProxyTest.kt	Adds proxy tests for getCurrentViewUrl() and cross-platform addActionWithHeatmap().
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/monitor/DatadogRumMonitorTest.kt	Updates tests for renamed heatmap fields and adds tests for cross-platform action + view URL cache behavior.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/instrumentation/gestures/GesturesListenerTapTest.kt	Updates native heatmap action capture type/imports.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/domain/scope/RumViewScopeTest.kt	Updates expectations to new heatmap resolver approach.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/domain/scope/RumRawEventExt.kt	Updates test helper event builder to renamed native heatmap field/type.
features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/domain/scope/RumActionScopeTest.kt	Adds cross-platform heatmap action resolution tests (id computation, preference, mismatch dropping).
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/Rum.kt	Passes appPackageName into DatadogRumMonitor.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/RumFeature.kt	Updates import for moved HeatmapIdentifierRegistryProvider.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/monitor/DatadogRumMonitor.kt	Adds view URL caching, app package name field, and cross-platform heatmap action entry point.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/monitor/AdvancedRumMonitor.kt	Extends internal monitor interface with cross-platform heatmap + view URL accessors.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/instrumentation/gestures/GesturesListener.kt	Updates native heatmap payload type and view key import package.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/instrumentation/gestures/AndroidActionTrackingStrategy.kt	Switches isValidTapTarget import to internal.utils.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/heatmaps/NativeHeatmapActionData.kt	Moves/renames native heatmap action payload into dedicated heatmaps package.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/heatmaps/HeatmapActionResolver.kt	Adds resolver to build DdAction from either native registry lookup or cross-platform hashing.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/domain/scope/RumRawEvent.kt	Adds fields for native vs cross-platform heatmap action data and app package name.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/domain/scope/RumActionScope.kt	Replaces inline heatmap resolution with HeatmapActionResolver selection and usage.
features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/_RumInternalProxy.kt	Exposes cross-platform heatmap action + current view URL methods.
features/dd-sdk-android-rum/api/dd-sdk-android-rum.api	Updates RUM API dump for new _RumInternalProxy methods.
features/dd-sdk-android-rum/api/apiSurface	Updates RUM API surface summary for new _RumInternalProxy methods.
dd-sdk-android-internal/src/test/java/com/datadog/android/internal/utils/TapTargetUtilsTest.kt	Moves test package to match TapTargetUtils new location.
dd-sdk-android-internal/src/test/java/com/datadog/android/heatmaps/HeatmapViewKeyTest.kt	Moves test package to match new public heatmapViewKey package.
dd-sdk-android-internal/src/main/java/com/datadog/android/internal/utils/TapTargetUtils.kt	Moves isValidTapTarget into internal.utils.
dd-sdk-android-internal/src/main/java/com/datadog/android/internal/heatmaps/HeatmapIdentifier.kt	Clarifies encoding contract and refactors hashing failure handling.
dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/HeatmapViewKey.kt	Moves heatmapViewKey into non-internal package.
dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/HeatmapIdentifierRegistryProvider.kt	Moves provider interface into non-internal package and expands KDoc.
dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/CrossPlatformHeatmapActionData.kt	Adds new public cross-platform heatmap payload type.
dd-sdk-android-internal/api/dd-sdk-android-internal.api	Updates internal module API dump for moved/added heatmap APIs and moved utils.
dd-sdk-android-internal/api/apiSurface	Updates internal module API surface summary accordingly.

Comments suppressed due to low confidence (2)

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

• The KDoc references [HeatmapIdentifier] but the type isn’t imported or fully qualified, which can produce an unresolved link in generated docs. Import HeatmapIdentifier (or fully qualify it) so the link resolves.
  dd-sdk-android-internal/src/main/java/com/datadog/android/heatmaps/HeatmapViewKey.kt:10
• After moving heatmapViewKey into com.datadog.android.heatmaps, the KDoc links [HeatmapIdentifier] and [HeatmapIdentifierRegistry] no longer resolve unless those types are imported (or fully qualified). Adding imports will keep generated docs/linking correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kikoveiga]

LGTM, Copilot's comment is very nit but maybe worth to take a look at.