From 30ffaafb4941a9ade01c11073250ad6816ff54db Mon Sep 17 00:00:00 2001
From: namArora3112 <namarora@adobe.com>
Date: Tue, 2 Sep 2025 09:54:17 +0530
Subject: [PATCH 1/3] PropositionItem class added along with unified track
 functionality  (#507)

* proposition item classes, track funcitonality etc

* proposition item uuid added

* json proposition item removed

* removed unused guide

* added htmlProposition , jsonPropositon item class

* removed unused apis of content card

* generatePropositionInteractionXdm removed

* ios implementation of track functionality

* uuid vs proposition  map added

* MessagingProposition class fixes

* get proposition for surfaces android fixes

* ios get proposition for surface fixes

* getproposition for surface updates

* MessagingView commented code removed

* removed proposition cache with parent

* clear cache in update proposition

* message util clean up

* proposition Item tracking usage refactored

* activityID extraction function reusable

* white space fixes

* added read me for track api usage

* removed unnecessary checks before calling track api for android native

* refactored extra null checks before calling track api at ios native side

* Addeed ios and android logs for null cases

* added comments and logs for android native code

* marked the trackContentCardInteraction and trackContentCardDisplay as deprecated

* added tests for propositionItem.track

* read me updated for proposition Item track usage

---------

Co-authored-by: Naman Arora <namarora+adobe@adobe.com>
---
 .../app/MessagingView.tsx                     |  42 ++++-
 packages/messaging/README.md                  |  51 +++++++
 .../__tests__/PropositionItemTests.ts         |  84 ++++++++++
 .../messaging/RCTAEPMessagingModule.java      | 143 +++++++++++++++---
 .../messaging/RCTAEPMessagingUtil.java        |   2 +-
 packages/messaging/ios/src/RCTAEPMessaging.mm |   8 +
 .../messaging/ios/src/RCTAEPMessaging.swift   | 104 ++++++++++++-
 .../ios/src/RCTAEPMessagingDataBridge.swift   |  19 +++
 packages/messaging/src/Messaging.ts           |  21 ++-
 packages/messaging/src/index.ts               |  18 ++-
 packages/messaging/src/models/ContentCard.ts  |  13 +-
 .../messaging/src/models/HTMLProposition.ts   |  21 ++-
 ...NPropositionItem.ts => JSONProposition.ts} |  21 ++-
 .../src/models/MessagingProposition.ts        |  48 +++++-
 .../src/models/MessagingPropositionItem.ts    |   8 +-
 .../messaging/src/models/PropositionItem.ts   | 135 +++++++++++++++++
 tests/jest/setup.ts                           |   1 +
 17 files changed, 685 insertions(+), 54 deletions(-)
 create mode 100644 packages/messaging/__tests__/PropositionItemTests.ts
 rename packages/messaging/src/models/{JSONPropositionItem.ts => JSONProposition.ts} (62%)
 create mode 100644 packages/messaging/src/models/PropositionItem.ts

diff --git a/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx b/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
index 270d5adbf..a53109f9b 100644
--- a/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
+++ b/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
@@ -13,13 +13,24 @@ governing permissions and limitations under the License.
 import React from 'react';
 import {Button, Text, View, ScrollView} from 'react-native';
 import {MobileCore} from '@adobe/react-native-aepcore';
-import {Messaging, PersonalizationSchema} from '@adobe/react-native-aepmessaging'
+import {
+  Messaging, 
+  PersonalizationSchema, 
+  MessagingEdgeEventType,
+  PropositionItem,
+  Message,
+  ContentCard,
+  HTMLProposition,
+  JSONPropositionItem
+} from '@adobe/react-native-aepmessaging'
+import { MessagingProposition } from '@adobe/react-native-aepmessaging';
 import styles from '../styles/styles';
 import { useRouter } from 'expo-router';
 
 const SURFACES = ['android-cbe-preview', 'cbe/json', 'android-cc'];
 const SURFACES_WITH_CONTENT_CARDS = ['android-cc'];
 
+
 const messagingExtensionVersion = async () => {
   const version = await Messaging.extensionVersion();
   console.log(`AdobeExperienceSDK: Messaging version: ${version}`);
@@ -40,12 +51,10 @@ const setMessagingDelegate = () => {
   });
   console.log('messaging delegate set');
 };
-
 const getPropositionsForSurfaces = async () => {
   const messages = await Messaging.getPropositionsForSurfaces(SURFACES);
   console.log(JSON.stringify(messages));
 };
-
 const trackAction = async () => {
   MobileCore.trackAction('tuesday', {full: true});
 };
@@ -75,7 +84,8 @@ const trackContentCardInteraction = async () => {
     for (const proposition of propositions) {
       for (const propositionItem of proposition.items) {
         if (propositionItem.schema === PersonalizationSchema.CONTENT_CARD) {
-          Messaging.trackContentCardInteraction(proposition, propositionItem);
+          // Cast to ContentCard for the legacy tracking method
+          Messaging.trackContentCardInteraction(proposition, propositionItem as any);
           console.log('trackContentCardInteraction', proposition, propositionItem);
         }
       }
@@ -93,7 +103,8 @@ const trackContentCardDisplay = async () => {
     for (const proposition of propositions) {
       for (const propositionItem of proposition.items) {
         if (propositionItem.schema === PersonalizationSchema.CONTENT_CARD) {
-          Messaging.trackContentCardDisplay(proposition, propositionItem);
+          // Cast to ContentCard for the legacy tracking method
+          Messaging.trackContentCardDisplay(proposition, propositionItem as any);
           console.log('trackContentCardDisplay', proposition, propositionItem);
         }
       }
@@ -101,6 +112,26 @@ const trackContentCardDisplay = async () => {
   }
 }
 
+
+// Method demonstrating unified tracking using PropositionItem methods
+const unifiedTrackingExample = async () => {
+  const messages = await Messaging.getPropositionsForSurfaces(SURFACES);  
+  for (const surface of SURFACES) { 
+    const propositions = messages[surface] || [];
+
+    for (const proposition of propositions) {
+      const propositionWrapper = new MessagingProposition(proposition);       
+      if (propositionWrapper.items.length > 0) {
+        const propositionItem = propositionWrapper.items[0];
+        propositionItem.track(MessagingEdgeEventType.DISPLAY); 
+        propositionItem.track('content_card_clicked', MessagingEdgeEventType.INTERACT, null);
+      }
+    }
+  }
+}
+
+
+
 function MessagingView() {
   const router = useRouter();
 
@@ -125,6 +156,7 @@ function MessagingView() {
         <Button title="trackAction()" onPress={trackAction} />
         <Button title="trackPropositionInteraction()" onPress={trackContentCardInteraction} />
         <Button title="trackContentCardDisplay()" onPress={trackContentCardDisplay} />
+        <Button title="Unified Tracking Example" onPress={unifiedTrackingExample} />
       </ScrollView>
     </View>
   );
diff --git a/packages/messaging/README.md b/packages/messaging/README.md
index 1c05aa3de..0439c43af 100644
--- a/packages/messaging/README.md
+++ b/packages/messaging/README.md
@@ -201,6 +201,53 @@ for (let item in proposition.items) {
 }
 ```
 
+
+### PropositionItem.track
+
+A unified tracking API is available for any proposition item (Content Cards, HTML, JSON, code-based items). You can use the same track() method regardless of content type, making your code more consistent and maintainable.
+
+#### Using PropositionItem.track (recommended)
+
+**Syntax**
+
+```javascript
+// Track display event
+propositionItem.track(MessagingEdgeEventType.DISPLAY);
+
+// Track interaction with custom data + event + optional tokens
+propositionItem.track(
+  interaction /* string | null */, 
+  MessagingEdgeEventType.INTERACT /* enum value */, 
+  [/* tokens */] /* string[] | null */
+);
+```
+
+When using `getPropositionsForSurfaces`, the returned objects can be wrapped with `MessagingProposition` to get typed items and convenient tracking via `PropositionItem.track(...)`.
+
+```javascript
+import { Messaging, MessagingProposition, MessagingEdgeEventType } from '@adobe/react-native-aepmessaging';
+
+const SURFACES = ['mobileapp://my-surface'];
+const messages = await Messaging.getPropositionsForSurfaces(SURFACES);
+
+for (const surface of SURFACES) {
+  const propositions = messages[surface] || [];
+
+  for (const proposition of propositions) {
+    const msgProp = new MessagingProposition(proposition);
+
+    if (msgProp.items.length > 0) {
+      const propositionItem = msgProp.items[0];
+
+      // Track interaction with custom data
+         propositionItem.track('content_card_clicked', MessagingEdgeEventType.INTERACT, null);
+     // Track with tokens for sub-item tracking
+        propositionItem.track('button_click', MessagingEdgeEventType.INTERACT, ['token-1', 'token-2']);
+    }
+  }
+}
+```
+
 ### getLatestMessage
 
 Retrieves the most recently displayed message object
@@ -440,6 +487,8 @@ function otherWorkflowFinished() {
 
 ### trackContentCardDisplay
 
+Deprecated: Use `PropositionItem.track(...)` instead. This API will be removed in a future release.
+
 Tracks a Display interaction with the given ContentCard
 
 **Syntax**
@@ -449,6 +498,8 @@ Messaging.trackContentCardDisplay(proposition, contentCard);
 
 ### trackContentCardInteraction
 
+Deprecated: Use `PropositionItem.track(...)` instead. This API will be removed in a future release.
+
 Tracks a Click interaction with the given ContentCard
 
 **Syntax**
diff --git a/packages/messaging/__tests__/PropositionItemTests.ts b/packages/messaging/__tests__/PropositionItemTests.ts
new file mode 100644
index 000000000..16833e705
--- /dev/null
+++ b/packages/messaging/__tests__/PropositionItemTests.ts
@@ -0,0 +1,84 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { NativeModules } from 'react-native';
+import { MessagingEdgeEventType, PropositionItem, PropositionItemData, PersonalizationSchema } from '../src';
+
+describe('PropositionItem', () => {
+  const uuid = 'activity-uuid-123';
+  const id = 'item-abc';
+  const activityID = uuid; // mirrors native mapping
+
+  const baseData: PropositionItemData = {
+    id,
+    uuid,
+    activityID,
+    schema: PersonalizationSchema.CONTENT_CARD,
+    data: { foo: 'bar' },
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('track(eventType) calls native with null interaction and tokens', () => {
+    const item = new PropositionItem(baseData);
+    item.track(MessagingEdgeEventType.DISPLAY);
+
+    expect(NativeModules.AEPMessaging.trackPropositionItem).toHaveBeenCalledWith(
+      activityID,
+      null,
+      MessagingEdgeEventType.DISPLAY,
+      null
+    );
+  });
+
+  it('track(interaction, eventType, tokens=null) forwards interaction', () => {
+    const item = new PropositionItem(baseData);
+    item.track('click', MessagingEdgeEventType.INTERACT, null);
+
+    expect(NativeModules.AEPMessaging.trackPropositionItem).toHaveBeenCalledWith(
+      activityID,
+      'click',
+      MessagingEdgeEventType.INTERACT,
+      null
+    );
+  });     
+
+  it('track(interaction, eventType, tokens[]) forwards tokens array', () => {
+    const item = new PropositionItem(baseData);
+    const tokens = ['t1', 't2'];
+    item.track('click', MessagingEdgeEventType.INTERACT, tokens);
+
+    expect(NativeModules.AEPMessaging.trackPropositionItem).toHaveBeenCalledWith(
+      activityID,
+      'click',
+      MessagingEdgeEventType.INTERACT,
+      tokens
+    );
+  });
+
+  it('track(null, eventType, tokens[]) supports null interaction with tokens', () => {
+    const item = new PropositionItem(baseData);
+    const tokens = ['a'];
+    item.track(null, MessagingEdgeEventType.DISPLAY, tokens);
+
+    expect(NativeModules.AEPMessaging.trackPropositionItem).toHaveBeenCalledWith(
+      activityID,
+      null,
+      MessagingEdgeEventType.DISPLAY,
+      tokens
+    );
+  });
+});
+
+
diff --git a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
index 2d52139a6..686a5fb3c 100644
--- a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
+++ b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
@@ -14,17 +14,17 @@
 import static com.adobe.marketing.mobile.reactnative.messaging.RCTAEPMessagingUtil.convertMessageToMap;
 
 import android.app.Activity;
+import android.util.Log;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import com.adobe.marketing.mobile.AdobeCallback;
 import com.adobe.marketing.mobile.AdobeCallbackWithError;
 import com.adobe.marketing.mobile.AdobeError;
-import com.adobe.marketing.mobile.LoggingMode;
 import com.adobe.marketing.mobile.Message;
 import com.adobe.marketing.mobile.Messaging;
 import com.adobe.marketing.mobile.MessagingEdgeEventType;
-import com.adobe.marketing.mobile.MobileCore;
 import com.adobe.marketing.mobile.messaging.MessagingUtils;
 import com.adobe.marketing.mobile.messaging.Proposition;
 import com.adobe.marketing.mobile.messaging.PropositionItem;
@@ -42,14 +42,56 @@
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.modules.core.DeviceEventManagerModule;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ConcurrentHashMap;
+
+
 
 public final class RCTAEPMessagingModule
     extends ReactContextBaseJavaModule implements PresentationDelegate {
+  // We cache uuid -> Proposition (not PropositionItem) for iOS parity: storing items on iOS lost
+  // weak parent references. Propositions currently contain a single item, so using the first item
+  // for tracking is valid.
+  private final Map<String, Proposition> propositionItemByUuid = new ConcurrentHashMap<>();
 
+  /**
+   * Parses the given Proposition and extracts the activity ID.
+   *
+   * Expected location: scopeDetails.activity.id in the proposition's event data.
+   * Returns null when any of the nested structures are missing or the id is not a String.
+   */
+  private String extractActivityId(Proposition proposition) {
+    try {
+      Map<String, Object> eventData = proposition.toEventData();
+      if (eventData == null) {
+        Log.d(TAG, "[MessagingBridge] Proposition toEventData() returned null; cannot extract activity.id");
+        return null;
+      }
+      Object scopeDetailsObj = eventData.get("scopeDetails");
+      if (!(scopeDetailsObj instanceof Map)) return null;
+      Map<String, Object> scopeDetails = (Map<String, Object>) scopeDetailsObj;
+      Object activityObj = scopeDetails.get("activity");
+      if (!(activityObj instanceof Map)) {
+        Log.d(TAG, "[MessagingBridge] Missing activity under scopeDetails; cannot extract activity.id");
+        return null;
+      }
+      Map<String, Object> activity = (Map<String, Object>) activityObj;
+      Object id = activity.get("id");
+      if (id instanceof String) {
+        return (String) id;
+      } else {
+        Log.d(TAG, "[MessagingBridge] Missing activity.id or not a String; skipping uuid cache mapping");
+        return null;
+      }
+    } catch (Exception e) {
+      Log.d(TAG, "[MessagingBridge] Exception extracting activity.id: " + e.getMessage(), e);
+      return null;
+    }
+  }
   private static final String TAG = "RCTAEPMessagingModule";
   private final Map<String, Message> messageCache = new HashMap<>();
   private final ReactApplicationContext reactContext;
@@ -100,21 +142,37 @@ public void getPropositionsForSurfaces(ReadableArray surfaces,
                                          final Promise promise) {
     String bundleId = this.reactContext.getPackageName();
     Messaging.getPropositionsForSurfaces(
-        RCTAEPMessagingUtil.convertSurfaces(surfaces),
-        new AdobeCallbackWithError<Map<Surface, List<Proposition>>>() {
-          @Override
-          public void fail(final AdobeError adobeError) {
-            promise.reject(adobeError.getErrorName(),
-                           "Unable to get Propositions");
-          }
-
-          @Override
-          public void call(
-              Map<Surface, List<Proposition>> propositionsMap) {
-            promise.resolve(RCTAEPMessagingUtil.convertSurfacePropositions(
-                propositionsMap, bundleId));
-          }
-        });
+            RCTAEPMessagingUtil.convertSurfaces(surfaces),
+            new AdobeCallbackWithError<Map<Surface, List<Proposition>>>() {
+              @Override
+              public void fail(final AdobeError adobeError) {
+                promise.reject(adobeError.getErrorName(),
+                        "Unable to get Propositions");
+              }
+
+              @Override
+              public void call(
+                      Map<Surface, List<Proposition>> propositionsMap) {
+                // Build UUID->Proposition map keyed by scopeDetails.activity.id
+                try {
+                  for (Map.Entry<Surface, List<Proposition>> entry : propositionsMap.entrySet()) {
+                    List<Proposition> propositions = entry.getValue();
+                    if (propositions == null) continue;
+                    for (Proposition proposition : propositions) {
+                      try {
+                        String key = extractActivityId(proposition);
+                        if (key != null) {
+                          propositionItemByUuid.put(key, proposition);
+                        }
+                      } catch (Throwable ignore) {}
+                    }
+                  }
+                } catch (Throwable ignore) {}
+
+                promise.resolve(RCTAEPMessagingUtil.convertSurfacePropositions(
+                        propositionsMap, bundleId));
+              }
+            });
   }
 
   @ReactMethod
@@ -131,6 +189,8 @@ public void setMessagingDelegate() {
   public void updatePropositionsForSurfaces(ReadableArray surfaces) {
     Messaging.updatePropositionsForSurfaces(
         RCTAEPMessagingUtil.convertSurfaces(surfaces));
+        propositionItemByUuid.clear();
+
   }
 
   // Message Methods
@@ -233,7 +293,6 @@ public boolean canShow(final Presentable<?> presentable) {
     if (shouldSaveMessage) {
       messageCache.put(message.getId(), message);
     }
-
     return shouldShowMessage;
   }
 
@@ -295,4 +354,52 @@ public void trackContentCardInteraction(ReadableMap propositionMap, ReadableMap
       }
     }
   }
+
+  /**
+   * Tracks interactions with a PropositionItem using the provided interaction and event type.
+   * This method is used by the React Native PropositionItem.track() method.
+   * 
+   * @param interaction A custom string value to be recorded in the interaction (nullable)
+   * @param eventType The MessagingEdgeEventType numeric value
+   * @param tokens Array containing the sub-item tokens for recording interaction (nullable)
+   */
+  @ReactMethod
+  public void trackPropositionItem(String uuid, @Nullable String interaction, int eventType, @Nullable ReadableArray tokens) {
+    try {
+      // Convert eventType int to MessagingEdgeEventType enum
+      final MessagingEdgeEventType edgeEventType = RCTAEPMessagingUtil.getEventType(eventType);
+      if (edgeEventType == null) {
+        return;
+      }
+      // Resolve PropositionItem by UUID
+      if (uuid == null) {
+        Log.d(TAG, "[MessagingBridge] Null uuid provided");
+        return;
+      }
+      final Proposition proposition = propositionItemByUuid.get(uuid);
+      if (proposition == null) {
+        Log.d(TAG, "[MessagingBridge] No cached proposition for uuid=" + uuid);
+        return;
+      }
+      final List<PropositionItem> items = proposition.getItems();
+      if (items == null || items.isEmpty()) {
+        return;
+      }
+      final PropositionItem propositionItem = items.get(0);
+
+      // Convert ReadableArray tokens -> List<String> (empty list if none)
+      List<String> tokenList = new ArrayList<>();
+      if (tokens != null) {
+        for (int i = 0; i < tokens.size(); i++) {
+          tokenList.add(tokens.getString(i));
+        }
+      }
+      Log.d(TAG, "[MessagingBridge] Tracking (direct) uuid=" + uuid + ", interaction=" + interaction + ", tokens=" + tokenList + ", eventType=" + edgeEventType.name());
+      propositionItem.track(interaction, edgeEventType, tokenList);
+
+    } catch (Exception e) {
+      Log.d(TAG, "Error tracking PropositionItem for uuid: " + uuid + ", error: " + e.getMessage(), e);
+    }
+  }
+
 }
diff --git a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingUtil.java b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingUtil.java
index ce6199ca5..a2faa185f 100644
--- a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingUtil.java
+++ b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingUtil.java
@@ -280,4 +280,4 @@ static List<Object> convertReadableArrayToList(final ReadableArray readableArray
         }
         return list;
     }
- }
+ }
\ No newline at end of file
diff --git a/packages/messaging/ios/src/RCTAEPMessaging.mm b/packages/messaging/ios/src/RCTAEPMessaging.mm
index 6a227ed73..76580fd09 100644
--- a/packages/messaging/ios/src/RCTAEPMessaging.mm
+++ b/packages/messaging/ios/src/RCTAEPMessaging.mm
@@ -55,4 +55,12 @@ @interface RCT_EXTERN_MODULE (RCTAEPMessaging, RCTEventEmitter)
                   : (NSDictionary *)propositionMap contentCardMap
                   : (NSDictionary *)contentCardMap);
 
+RCT_EXTERN_METHOD(trackPropositionItem
+                  : (NSString *)uuid interaction
+                  : (NSString * _Nullable)interaction eventType
+                  : (NSInteger)eventType tokens
+                  : (NSArray<NSString *> * _Nullable)tokens withResolver
+                  : (RCTPromiseResolveBlock)resolve withRejecter
+                  : (RCTPromiseRejectBlock)reject);
+
 @end
diff --git a/packages/messaging/ios/src/RCTAEPMessaging.swift b/packages/messaging/ios/src/RCTAEPMessaging.swift
index 4c8a112b8..3629a1a38 100644
--- a/packages/messaging/ios/src/RCTAEPMessaging.swift
+++ b/packages/messaging/ios/src/RCTAEPMessaging.swift
@@ -64,7 +64,7 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
     ) {
         resolve(self.latestMessage != nil ? RCTAEPMessagingDataBridge.transformToMessage(message: self.latestMessage!) : nil)
     }
-
+      
     @objc
     func getPropositionsForSurfaces(
         _ surfaces: [String],
@@ -72,16 +72,29 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         withRejecter reject: @escaping RCTPromiseRejectBlock
     ) {
         let surfacePaths = surfaces.map { $0.isEmpty ? Surface() : Surface(path: $0) }
-        Messaging.getPropositionsForSurfaces(surfacePaths) { propositions, error in
+        Messaging.getPropositionsForSurfaces(surfacePaths) { [weak self] propositions, error in
+            guard let self = self else { return }
             guard error == nil else {
                 reject("Unable to Retrieve Propositions", nil, nil)
                 return
             }
-            if (propositions != nil && propositions!.isEmpty) {
-                resolve([String: Any]());
-                return;
+            guard let propositions = propositions, !propositions.isEmpty else {
+                resolve([String: Any]())
+                return
             }
-            resolve(RCTAEPMessagingDataBridge.transformPropositionDict(dict: propositions!))
+
+            // Populate uuid->Proposition map using scopeDetails.activity.id
+            for (_, list) in propositions {
+                for proposition in list {
+                    if let pMap = proposition.asDictionary() {
+                        if let key = RCTAEPMessagingDataBridge.extractActivityId(from: pMap) {
+                            self.propositionByUuid[key] = proposition
+                        }
+                    }
+                }
+            }
+
+            resolve(RCTAEPMessagingDataBridge.transformPropositionDict(dict: propositions))
         }
     }
 
@@ -113,6 +126,7 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
     ) {
         let mapped = surfaces.map { Surface(path: $0) }
         Messaging.updatePropositionsForSurfaces(mapped)
+        propositionByUuid.removeAll()
         resolve(nil)
     }
 
@@ -249,6 +263,67 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         }
     }
 
+    /// MARK: - Unified PropositionItem Tracking Methods
+    
+    /**
+     * Tracks interactions with a PropositionItem using the provided interaction and event type.
+     * This method is used by the React Native PropositionItem.track() method.
+     * 
+     * - Parameters:
+     *   - uuid: The UUID mapped to the PropositionItem (derived from activityId)
+     *   - interaction: A custom string value to be recorded in the interaction (optional)
+     *   - eventType: The MessagingEdgeEventType numeric value
+     *   - tokens: Array containing the sub-item tokens for recording interaction (optional)
+     */
+
+    @objc
+    func trackPropositionItem(
+        _ uuid: String,
+        interaction: String?,
+        eventType: Int,
+        tokens: [String]?,
+        withResolver resolve: @escaping RCTPromiseResolveBlock,
+        withRejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        NSLog("[MessagingBridge] trackPropositionItem called with eventType=\(eventType), uuid=\(uuid), interaction=\(String(describing: interaction)), tokens=\(String(describing: tokens))")
+
+        guard !uuid.isEmpty else {
+            NSLog("[MessagingBridge] Empty uuid provided; no-op.")
+            resolve(nil)
+            return
+        }
+
+        guard let proposition = propositionByUuid[uuid] else {
+            NSLog("[MessagingBridge] No cached proposition for uuid=\(uuid); no-op.")
+            resolve(nil)
+            return
+        }
+
+        NSLog("[MessagingBridge] Found proposition for uuid=\(uuid). scope=\(proposition.scope), items=\(proposition.items.count)")
+
+        // Event type mapping (Android parity)
+        let edgeEventType = mapEdgeEventType(eventType) ?? .display
+
+        // Track on the first item under this proposition
+        guard let item = proposition.items.first else {
+            NSLog("[MessagingBridge] Proposition for uuid=\(uuid) has no items; no-op.")
+            resolve(nil)
+            return
+        }
+
+        // Direct call without normalization (expecting valid inputs)
+        NSLog("[MessagingBridge] Tracking (direct) uuid=\(uuid), interaction=\(String(describing: interaction)), tokens=\(String(describing: tokens)), eventType=\(edgeEventType.rawValue)")
+        item.track(interaction, withEdgeEventType: edgeEventType, forTokens: tokens)
+
+        NSLog("[MessagingBridge] Tracking complete for uuid=\(uuid)")
+        resolve(nil)
+    }
+
+
+
+    // Map uuid (scopeDetails.activity.id) -> parent Proposition
+    private var propositionByUuid = [String: Proposition]()
+   
     // Messaging Delegate Methods
     public func onDismiss(message: Showable) {
         if let fullscreenMessage = message as? FullscreenMessage,
@@ -328,3 +403,20 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         RCTAEPMessaging.emitter.sendEvent(withName: name, body: body)
     }
 }
+
+// MARK: - Private helpers
+private extension RCTAEPMessaging {
+    /// Maps JS MessagingEdgeEventType integer values to AEPMessaging.MessagingEdgeEventType cases
+    /// JS enum values: DISMISS=0, INTERACT=1, TRIGGER=2, DISPLAY=3, PUSH_APPLICATION_OPENED=4, PUSH_CUSTOM_ACTION=5
+    func mapEdgeEventType(_ value: Int) -> MessagingEdgeEventType? {
+        switch value {
+        case 0: return .dismiss
+        case 1: return .interact
+        case 2: return .trigger
+        case 3: return .display
+        case 4: return .pushApplicationOpened
+        case 5: return .pushCustomAction
+        default: return nil
+        }
+    }
+}
diff --git a/packages/messaging/ios/src/RCTAEPMessagingDataBridge.swift b/packages/messaging/ios/src/RCTAEPMessagingDataBridge.swift
index a6a678db9..3e2fdaee6 100644
--- a/packages/messaging/ios/src/RCTAEPMessagingDataBridge.swift
+++ b/packages/messaging/ios/src/RCTAEPMessagingDataBridge.swift
@@ -27,4 +27,23 @@ public class RCTAEPMessagingDataBridge: NSObject {
                 .map({ $0.asDictionary() })
         }
     }
+
+    /// Extracts the activity identifier from a proposition dictionary at scopeDetails.activity.id
+    static func extractActivityId(from propositionDict: [String: Any]) -> String? {
+        guard let scopeDetails = propositionDict["scopeDetails"] as? [String: Any] else {
+            NSLog("[MessagingBridge] Missing scopeDetails on proposition; cannot extract activity.id")
+            return nil
+        }
+
+        guard let activity = scopeDetails["activity"] as? [String: Any] else {
+            NSLog("[MessagingBridge] Missing activity under scopeDetails; cannot extract activity.id")
+            return nil
+        }
+
+        guard let id = activity["id"] as? String, !id.isEmpty else {
+            NSLog("[MessagingBridge] Missing or empty activity.id; skipping uuid cache mapping")
+            return nil
+        }
+        return id
+    }
 }
diff --git a/packages/messaging/src/Messaging.ts b/packages/messaging/src/Messaging.ts
index 25cecdbb3..34100d757 100644
--- a/packages/messaging/src/Messaging.ts
+++ b/packages/messaging/src/Messaging.ts
@@ -37,6 +37,7 @@ export interface NativeMessagingModule {
   updatePropositionsForSurfaces: (surfaces: string[]) => void;
   trackContentCardDisplay: (proposition: MessagingProposition, contentCard: ContentCard) => void;
   trackContentCardInteraction: (proposition: MessagingProposition, contentCard: ContentCard) => void;
+  trackPropositionItem: (itemId: string, interaction: string | null, eventType: number, tokens: string[] | null) => void;
 }
 
 const RCTAEPMessaging: NativeModule & NativeMessagingModule =
@@ -92,15 +93,33 @@ class Messaging {
   ): Promise<Record<string, MessagingProposition[]>> {
     return await RCTAEPMessaging.getPropositionsForSurfaces(surfaces);
   }
-
+  /**
+   * @deprecated Use PropositionItem.track(...) instead. Will be removed in vX.Y.Z.
+   */
   static trackContentCardDisplay(proposition: MessagingProposition, contentCard: ContentCard): void {
     RCTAEPMessaging.trackContentCardDisplay(proposition, contentCard);
   }
 
+  /**
+   * @deprecated Use PropositionItem.track(...) instead. Will be removed in vX.Y.Z.
+   */
   static trackContentCardInteraction(proposition: MessagingProposition, contentCard: ContentCard): void {
     RCTAEPMessaging.trackContentCardInteraction(proposition, contentCard);
   }
 
+  /**
+   * Tracks interactions with a PropositionItem using the provided interaction and event type.
+   * This method is used internally by the PropositionItem.track() method.
+   * 
+   * @param {string} itemId - The unique identifier of the PropositionItem
+   * @param {string | null} interaction - A custom string value to be recorded in the interaction
+   * @param {number} eventType - The MessagingEdgeEventType numeric value
+   * @param {string[] | null} tokens - Array containing the sub-item tokens for recording interaction
+   */
+  static trackPropositionItem(itemId: string, interaction: string | null, eventType: number, tokens: string[] | null): void {
+    RCTAEPMessaging.trackPropositionItem(itemId, interaction, eventType, tokens);
+  }
+
   /**
    * Function to set the UI Message delegate to listen the Message lifecycle events.
    * @returns A function to unsubscribe from all event listeners
diff --git a/packages/messaging/src/index.ts b/packages/messaging/src/index.ts
index ba54a59d1..469b20538 100644
--- a/packages/messaging/src/index.ts
+++ b/packages/messaging/src/index.ts
@@ -11,25 +11,27 @@ governing permissions and limitations under the License.
 */
 
 import Messaging from './Messaging';
-import { ContentCard } from './models/ContentCard';
-import { HTMLProposition } from './models/HTMLProposition';
+import { ContentCard, ContentCardData } from './models/ContentCard';
+
 import { InAppMessage } from './models/InAppMessage';
-import { JSONPropositionItem } from './models/JSONPropositionItem';
+import { HTMLProposition, HTMLPropositionData } from './models/HTMLProposition';
+import { JSONPropositionItem, JSONPropositionData } from './models/JSONProposition';
+
 import Message from './models/Message';
 import { MessagingDelegate } from './models/MessagingDelegate';
 import MessagingEdgeEventType from './models/MessagingEdgeEventType';
 import { MessagingProposition } from './models/MessagingProposition';
 import { MessagingPropositionItem } from './models/MessagingPropositionItem';
 import { PersonalizationSchema } from './models/PersonalizationSchema';
+import { PropositionItem, PropositionItemData } from './models/PropositionItem';
 import { Activity, Characteristics } from './models/ScopeDetails';
 
 export {
   Activity,
   Characteristics,
   ContentCard,
-  HTMLProposition,
+  ContentCardData,
   InAppMessage,
-  JSONPropositionItem,
   Messaging,
   Message,
   MessagingDelegate,
@@ -37,4 +39,10 @@ export {
   MessagingProposition,
   MessagingPropositionItem,
   PersonalizationSchema,
+  PropositionItem,
+  PropositionItemData,
+  HTMLProposition,
+  HTMLPropositionData,
+  JSONPropositionItem,
+  JSONPropositionData,
 };
diff --git a/packages/messaging/src/models/ContentCard.ts b/packages/messaging/src/models/ContentCard.ts
index f732d8f80..d6d299612 100644
--- a/packages/messaging/src/models/ContentCard.ts
+++ b/packages/messaging/src/models/ContentCard.ts
@@ -11,11 +11,12 @@
 */
 
 import { PersonalizationSchema } from './PersonalizationSchema';
+import { PropositionItem, PropositionItemData } from './PropositionItem';
 
 type ContentCardTemplate = 'SmallImage';
 type DismissButtonStyle = 'circle' | 'none' | 'simple';
 
-export interface ContentCard {
+export interface ContentCardData extends PropositionItemData {
   id: string;
   data: {
     contentType: 'application/json';
@@ -45,3 +46,13 @@ export interface ContentCard {
   };
   schema: PersonalizationSchema.CONTENT_CARD;
 }
+
+export class ContentCard extends PropositionItem {
+  declare data: ContentCardData['data']; // Override data type for better typing
+
+  constructor(contentCardData: ContentCardData) {
+    super(contentCardData);
+    this.data = contentCardData.data;
+  }
+
+}
diff --git a/packages/messaging/src/models/HTMLProposition.ts b/packages/messaging/src/models/HTMLProposition.ts
index c966ed4c4..6714b3d89 100644
--- a/packages/messaging/src/models/HTMLProposition.ts
+++ b/packages/messaging/src/models/HTMLProposition.ts
@@ -11,11 +11,20 @@
 */
 
 import { PersonalizationSchema } from './PersonalizationSchema';
+import { PropositionItem, PropositionItemData } from './PropositionItem';
 
-export interface HTMLProposition {
-  id: string;
-  data: {
-    content: string;
-  };
-  schema: PersonalizationSchema.HTML_CONTENT;
+export interface HTMLPropositionData extends PropositionItemData {
+	data: {
+		content: string;
+	};
+	schema: PersonalizationSchema.HTML_CONTENT;
 }
+
+export class HTMLProposition extends PropositionItem {
+	declare data: HTMLPropositionData['data'];
+
+	constructor(htmlData: HTMLPropositionData) {
+		super(htmlData);
+		this.data = htmlData.data;
+	}
+}
\ No newline at end of file
diff --git a/packages/messaging/src/models/JSONPropositionItem.ts b/packages/messaging/src/models/JSONProposition.ts
similarity index 62%
rename from packages/messaging/src/models/JSONPropositionItem.ts
rename to packages/messaging/src/models/JSONProposition.ts
index 8ae5dfa28..6fdd55f0c 100644
--- a/packages/messaging/src/models/JSONPropositionItem.ts
+++ b/packages/messaging/src/models/JSONProposition.ts
@@ -11,11 +11,20 @@
 */
 
 import { PersonalizationSchema } from './PersonalizationSchema';
+import { PropositionItem, PropositionItemData } from './PropositionItem';
 
-export interface JSONPropositionItem {
-  id: string;
-  data: {
-    content: string;
-  };
-  schema: PersonalizationSchema.JSON_CONTENT;
+export interface JSONPropositionData extends PropositionItemData {
+	data: {
+		content: any;
+	};
+	schema: PersonalizationSchema.JSON_CONTENT;
 }
+
+export class JSONPropositionItem extends PropositionItem {
+	declare data: JSONPropositionData['data'];
+
+	constructor(jsonData: JSONPropositionData) {
+		super(jsonData);
+		this.data = jsonData.data;
+	}
+}
\ No newline at end of file
diff --git a/packages/messaging/src/models/MessagingProposition.ts b/packages/messaging/src/models/MessagingProposition.ts
index 7fda707e4..d6c404320 100644
--- a/packages/messaging/src/models/MessagingProposition.ts
+++ b/packages/messaging/src/models/MessagingProposition.ts
@@ -10,12 +10,54 @@
     language governing permissions and limitations under the License.
 */
 
-import { MessagingPropositionItem } from './MessagingPropositionItem';
 import { ScopeDetails } from './ScopeDetails';
+import { PersonalizationSchema } from './PersonalizationSchema';
+import { ContentCard } from './ContentCard';
+import { HTMLProposition } from './HTMLProposition';
+import { JSONPropositionItem } from './JSONProposition';
+import { PropositionItem } from './PropositionItem';
 
-export interface MessagingProposition {
+export class MessageProposition {
   id: string;
   scope: string;
   scopeDetails: ScopeDetails;
-  items: MessagingPropositionItem[];
+  items: PropositionItem[];
+
+  constructor(raw: { id: string; scope: string; scopeDetails: ScopeDetails; items?: any[] }) {
+    this.id = raw?.id ?? '';
+    this.scope = raw?.scope ?? '';
+    this.scopeDetails = (raw?.scopeDetails as ScopeDetails) ?? ({} as ScopeDetails);
+
+    // Mirror activity.id into activity.activityID for convenience
+    const activityIdFromScope = this.scopeDetails?.activity?.id ?? '';
+    if (this.scopeDetails?.activity) {
+      (this.scopeDetails.activity as any).activityID = activityIdFromScope;
+    }
+
+    const rawItems = Array.isArray(raw?.items) ? raw.items : [];
+    this.items = rawItems.map((itemData: any) => {
+      const activityId = this.scopeDetails?.activity?.id ?? '';
+      let instance: any;
+      switch (itemData?.schema) {
+        case PersonalizationSchema.CONTENT_CARD:
+          instance = new ContentCard(itemData as any);
+          (instance as any).activityID = activityId;
+          return instance;
+        case PersonalizationSchema.HTML_CONTENT:
+          instance = new HTMLProposition(itemData as any);
+          (instance as any).activityID = activityId;
+          return instance;
+        case PersonalizationSchema.JSON_CONTENT:
+          instance = new JSONPropositionItem(itemData as any);
+          (instance as any).activityID = activityId;
+          return instance;
+        default:
+          instance = new PropositionItem(itemData as any);
+          (instance as any).activityID = activityId;
+          return instance;
+      }
+    });
+  }
 }
+
+export { MessageProposition as MessagingProposition };
diff --git a/packages/messaging/src/models/MessagingPropositionItem.ts b/packages/messaging/src/models/MessagingPropositionItem.ts
index 65d418660..25c752cf8 100644
--- a/packages/messaging/src/models/MessagingPropositionItem.ts
+++ b/packages/messaging/src/models/MessagingPropositionItem.ts
@@ -12,11 +12,15 @@
 
 import { ContentCard } from './ContentCard';
 import { HTMLProposition } from './HTMLProposition';
-import { JSONPropositionItem } from './JSONPropositionItem';
+import { JSONPropositionItem } from './JSONProposition';
 import { InAppMessage } from './InAppMessage';
+import { PropositionItem } from './PropositionItem';
 
+// Union type for all possible proposition item types
+// All items now extend PropositionItem and have unified tracking capabilities
 export type MessagingPropositionItem =
   | ContentCard
   | HTMLProposition
   | InAppMessage
-  | JSONPropositionItem;
+  | JSONPropositionItem
+  | PropositionItem;
diff --git a/packages/messaging/src/models/PropositionItem.ts b/packages/messaging/src/models/PropositionItem.ts
new file mode 100644
index 000000000..5eaa1c2a2
--- /dev/null
+++ b/packages/messaging/src/models/PropositionItem.ts
@@ -0,0 +1,135 @@
+/*
+    Copyright 2025 Adobe. All rights reserved.
+    This file is licensed to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
+    or agreed to in writing, software distributed under the License is
+    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF
+    ANY KIND, either express or implied. See the License for the specific
+    language governing permissions and limitations under the License.
+*/
+
+import { NativeModules } from 'react-native';
+import { PersonalizationSchema } from './PersonalizationSchema';
+import MessagingEdgeEventType from './MessagingEdgeEventType';
+
+const RCTAEPMessaging = NativeModules.AEPMessaging;
+
+/**
+ * Base PropositionItem interface that all proposition items implement
+ */
+export interface PropositionItemData {
+  id: string;
+  uuid: string;
+  schema: PersonalizationSchema;
+  activityID: string;
+  data: {
+    [key: string]: any;
+  };
+}
+
+/**
+ * A PropositionItem represents a personalization JSON object returned by Konductor.
+ * This is the base class that provides tracking functionality for all proposition items
+ * including ContentCards, InApp messages, and code-based experiences.
+ * 
+ * This mirrors the native Android PropositionItem class functionality.
+ */
+export class PropositionItem {
+  id: string;
+  uuid: string;
+  activityID: string;
+  schema: PersonalizationSchema;
+  data: { [key: string]: any };
+
+  constructor(propositionItemData: PropositionItemData) {
+    this.id = propositionItemData.id;
+    this.schema = propositionItemData.schema;
+    this.data = propositionItemData.data;
+    this.uuid = propositionItemData.uuid;
+    this.activityID = propositionItemData.activityID;
+  }
+
+  /**
+   * Gets the PropositionItem identifier.
+   * 
+   * @returns {string} The PropositionItem identifier
+   */
+  getItemId(): string {
+    return this.id;
+  }
+
+  /**
+   * Gets the PropositionItem content schema.
+   * 
+   * @returns {PersonalizationSchema} The PropositionItem content schema
+   */
+  getSchema(): PersonalizationSchema {
+    return this.schema;
+  }
+
+  /**
+   * Gets the PropositionItem data.
+   * 
+   * @returns {object} The PropositionItem data
+   */
+  getItemData(): { [key: string]: any } {
+    return this.data;
+  }
+
+  /**
+   * Tracks interaction with this proposition item.
+   * This is the core tracking method that all proposition items use.
+   * 
+   * @param {MessagingEdgeEventType} eventType - The MessagingEdgeEventType specifying event type for the interaction
+   * 
+   * @example
+   * propositionItem.track(MessagingEdgeEventType.DISPLAY);
+   */
+  track(eventType: MessagingEdgeEventType): void;
+  
+  /**
+   * Tracks interaction with this proposition item.
+   * 
+   * @param {string | null} interaction - String describing the interaction
+   * @param {MessagingEdgeEventType} eventType - The MessagingEdgeEventType specifying event type for the interaction
+   * @param {string[] | null} tokens - Array containing the sub-item tokens for recording interaction
+   * 
+   * @example
+   * // Track display
+   * propositionItem.track(null, MessagingEdgeEventType.DISPLAY, null);
+   * 
+   * // Track interaction
+   * propositionItem.track("button_clicked", MessagingEdgeEventType.INTERACT, null);
+   * 
+   * // Track with tokens
+   * propositionItem.track("click", MessagingEdgeEventType.INTERACT, ["token1", "token2"]);
+   */
+  track(interaction: string | null, eventType: MessagingEdgeEventType, tokens: string[] | null): void;
+
+  // Implementation
+  track(
+    interactionOrEventType: string | null | MessagingEdgeEventType,
+    eventType?: MessagingEdgeEventType,
+    tokens?: string[] | null
+  ): void {
+    // Handle overloaded method signatures
+    if (typeof interactionOrEventType === 'number' && eventType === undefined) {
+      // First overload: track(eventType)
+      this.trackWithDetails(null, interactionOrEventType, null);
+    } else if (typeof interactionOrEventType === 'string' || interactionOrEventType === null) {
+      // Second overload: track(interaction, eventType, tokens)
+      this.trackWithDetails(interactionOrEventType, eventType!, tokens || null);
+    }
+  }
+
+  /**
+   * Internal method that performs the actual tracking
+   */
+  private trackWithDetails(interaction: string | null, eventType: MessagingEdgeEventType, tokens: string[] | null): void {
+    const nativeIdentifier = this.activityID ?? null;
+    RCTAEPMessaging.trackPropositionItem(nativeIdentifier, interaction, eventType, tokens);
+  }
+
+} 
\ No newline at end of file
diff --git a/tests/jest/setup.ts b/tests/jest/setup.ts
index a1b1de46a..562e1f941 100644
--- a/tests/jest/setup.ts
+++ b/tests/jest/setup.ts
@@ -157,6 +157,7 @@ jest.doMock('react-native', () => {
           getPropositionsForSurfaces: jest.fn(
             () => new Promise((resolve) => resolve([]))
           ),
+          trackPropositionItem: jest.fn(),
           trackContentCardDisplay: jest.fn(),
           trackContentCardInteraction: jest.fn()
         },

From 78a650feddbbdba214ecfde06ec875a3380c18a1 Mon Sep 17 00:00:00 2001
From: Ishita Gambhir <igambhir@adobe.com>
Date: Wed, 3 Sep 2025 13:04:23 +0530
Subject: [PATCH 2/3] add handleJavascriptMessage in AEPMessaging (#519)

* Messaging - handle javascript message

* add js event listener and ios

* typecaste Message object

* address PR comments

* refactor log statements

* address PR comments

* revert env file id changes

* clear js handler when onDismiss is called
---
 .../app/MessagingView.tsx                     | 11 ++-
 packages/messaging/README.md                  | 17 ++++-
 .../messaging/__tests__/MessagingTests.ts     | 11 +++
 .../messaging/RCTAEPMessagingConstants.java   | 19 ++++++
 .../messaging/RCTAEPMessagingModule.java      | 26 +++++++
 packages/messaging/ios/src/RCTAEPMessaging.mm |  5 ++
 .../messaging/ios/src/RCTAEPMessaging.swift   | 25 +++++++
 .../ios/src/RCTAEPMessagingConstants.swift    |  6 +-
 packages/messaging/src/Messaging.ts           | 24 ++++---
 packages/messaging/src/models/Message.ts      | 52 +++++++++++++-
 .../messaging/tutorials/In-App Messaging.md   | 67 +++++++++++++++++++
 11 files changed, 245 insertions(+), 18 deletions(-)
 create mode 100644 packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingConstants.java
 create mode 100644 packages/messaging/tutorials/In-App Messaging.md

diff --git a/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx b/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
index a53109f9b..4d82cdc9d 100644
--- a/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
+++ b/apps/AEPSampleAppNewArchEnabled/app/MessagingView.tsx
@@ -44,7 +44,12 @@ const refreshInAppMessages = () => {
 const setMessagingDelegate = () => {
   Messaging.setMessagingDelegate({
     onDismiss: msg => console.log('dismissed!', msg),
-    onShow: msg => console.log('show', msg),
+    onShow: msg => {
+      console.log('show', msg);
+      msg.handleJavascriptMessage('myInappCallback', (content: string) => {
+        console.log('Received webview content in onShow:', content);
+      });
+    },
     shouldShowMessage: () => true,
     shouldSaveMessage: () => true,
     urlLoaded: (url, message) => console.log(url, message),
@@ -53,10 +58,10 @@ const setMessagingDelegate = () => {
 };
 const getPropositionsForSurfaces = async () => {
   const messages = await Messaging.getPropositionsForSurfaces(SURFACES);
-  console.log(JSON.stringify(messages));
+  console.log('getPropositionsForSurfaces', JSON.stringify(messages));
 };
 const trackAction = async () => {
-  MobileCore.trackAction('tuesday', {full: true});
+  MobileCore.trackAction('iamjs', {full: true});
 };
 
 const updatePropositionsForSurfaces = async () => {
diff --git a/packages/messaging/README.md b/packages/messaging/README.md
index 0439c43af..58fca58d7 100644
--- a/packages/messaging/README.md
+++ b/packages/messaging/README.md
@@ -387,6 +387,20 @@ var message: Message;
 message.clear();
 ```
 
+### handleJavascriptMessage
+
+Registers a javascript interface for the provided handler name to the WebView associated with the InAppMessage presentation to handle Javascript messages. When the registered handlers are executed via the HTML the result will be passed back to the associated handler.
+
+**Syntax**
+
+```typescript
+handleJavascriptMessage(handlerName: string, handler: (content: string) => void);
+```
+
+**Example**
+
+It can be used for the native handling of JavaScript events. Please refer to the [tutorial](./tutorials/In-App%20Messaging.md#native-handling-of-javascript-events) for more information.
+
 ## Programmatically control the display of in-app messages
 
 App developers can now create a type `MessagingDelegate` in order to be alerted when specific events occur during the lifecycle of an in-app message.
@@ -509,5 +523,4 @@ Messaging.trackContentCardInteraction(proposition, contentCard);
 
 
 ## Tutorials
-[Content Cards](./tutorials/ContentCards.md)
-
+[Native handling of Javascript Events](./tutorials/In-App%20Messaging.md)
diff --git a/packages/messaging/__tests__/MessagingTests.ts b/packages/messaging/__tests__/MessagingTests.ts
index f0ed77cd8..c27edfe4a 100644
--- a/packages/messaging/__tests__/MessagingTests.ts
+++ b/packages/messaging/__tests__/MessagingTests.ts
@@ -87,6 +87,17 @@ describe('Messaging', () => {
     expect(spy).toHaveBeenCalledWith(id);
   });
 
+  it('handleJavascriptMessage is called', async () => {
+    const spy = jest.spyOn(NativeModules.AEPMessaging, 'handleJavascriptMessage');
+    let id = 'id';
+    let autoTrack = true;
+    let message = new Message({id, autoTrack});
+    let handlerName = 'handlerName';
+    let handler = jest.fn();
+    await message.handleJavascriptMessage(handlerName, handler);
+    expect(spy).toHaveBeenCalledWith(id, handlerName);
+  });
+
   it('should call updatePropositionsForSurfaces', async () => {
     const spy = jest.spyOn(NativeModules.AEPMessaging, 'updatePropositionsForSurfaces');
     await Messaging.updatePropositionsForSurfaces([
diff --git a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingConstants.java b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingConstants.java
new file mode 100644
index 000000000..445c19c0f
--- /dev/null
+++ b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingConstants.java
@@ -0,0 +1,19 @@
+/*
+    Copyright 2025 Adobe. All rights reserved.
+    This file is licensed to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
+    or agreed to in writing, software distributed under the License is
+    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF
+    ANY KIND, either express or implied. See the License for the specific
+    language governing permissions and limitations under the License.
+ */
+package com.adobe.marketing.mobile.reactnative.messaging;
+
+class RCTAEPMessagingConstants {
+    static final String MESSAGE_ID_KEY = "messageId";
+    static final String HANDLER_NAME_KEY = "handlerName";
+    static final String CONTENT_KEY = "content";
+    static final String ON_JAVASCRIPT_MESSAGE_EVENT = "onJavascriptMessage";
+ }
diff --git a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
index 686a5fb3c..815cdbc8a 100644
--- a/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
+++ b/packages/messaging/android/src/main/java/com/adobe/marketing/mobile/reactnative/messaging/RCTAEPMessagingModule.java
@@ -31,6 +31,7 @@
 import com.adobe.marketing.mobile.messaging.Surface;
 import com.adobe.marketing.mobile.services.ServiceProvider;
 import com.adobe.marketing.mobile.services.ui.InAppMessage;
+import com.adobe.marketing.mobile.services.ui.message.InAppMessageEventHandler;
 import com.adobe.marketing.mobile.services.ui.Presentable;
 import com.adobe.marketing.mobile.services.ui.PresentationDelegate;
 import com.facebook.react.bridge.Arguments;
@@ -99,6 +100,7 @@ private String extractActivityId(Proposition proposition) {
   private boolean shouldShowMessage = false;
   private CountDownLatch latch = new CountDownLatch(1);
   private Message latestMessage = null;
+  private final Map<String, Presentable<?>> presentableCache = new HashMap<>();
 
   public RCTAEPMessagingModule(ReactApplicationContext reactContext) {
     super(reactContext);
@@ -235,11 +237,33 @@ public void track(final String messageId, final String interaction,
     }
   }
 
+  @ReactMethod
+  public void handleJavascriptMessage(final String messageId, final String handlerName) {
+    Presentable<?> presentable = presentableCache.get(messageId);
+    if (presentable == null || !(presentable.getPresentation() instanceof InAppMessage)) {
+      Log.w(TAG, "handleJavascriptMessage: No presentable found for messageId: " + messageId);
+      return;
+    }
+
+    Presentable<InAppMessage> inAppMessagePresentable = (Presentable<InAppMessage>) presentable;
+    InAppMessageEventHandler eventHandler = inAppMessagePresentable.getPresentation().getEventHandler();
+
+    eventHandler.handleJavascriptMessage(handlerName, content -> {
+      Map<String, String> params = new HashMap<>();
+      params.put(RCTAEPMessagingConstants.MESSAGE_ID_KEY, messageId);
+      params.put(RCTAEPMessagingConstants.HANDLER_NAME_KEY, handlerName);
+      params.put(RCTAEPMessagingConstants.CONTENT_KEY, content);
+      emitEvent(RCTAEPMessagingConstants.ON_JAVASCRIPT_MESSAGE_EVENT, params);
+    });
+  }
+
   // Messaging Delegate functions
   @Override
   public void onShow(final Presentable<?> presentable) {
     if (!(presentable.getPresentation() instanceof InAppMessage)) return;
     Message message = MessagingUtils.getMessageForPresentable((Presentable<InAppMessage>) presentable);
+    presentableCache.put(message.getId(), presentable);
+
     if (message != null) {
       Map<String, String> data =
           convertMessageToMap(message);
@@ -251,6 +275,8 @@ public void onShow(final Presentable<?> presentable) {
   public void onDismiss(final Presentable<?> presentable) {
     if (!(presentable.getPresentation() instanceof InAppMessage)) return;
     Message message = MessagingUtils.getMessageForPresentable((Presentable<InAppMessage>) presentable);
+    presentableCache.remove(message.getId());
+    
     if (message != null) {
       Map<String, String> data =
           convertMessageToMap(message);
diff --git a/packages/messaging/ios/src/RCTAEPMessaging.mm b/packages/messaging/ios/src/RCTAEPMessaging.mm
index 76580fd09..8c85ca9b6 100644
--- a/packages/messaging/ios/src/RCTAEPMessaging.mm
+++ b/packages/messaging/ios/src/RCTAEPMessaging.mm
@@ -55,6 +55,11 @@ @interface RCT_EXTERN_MODULE (RCTAEPMessaging, RCTEventEmitter)
                   : (NSDictionary *)propositionMap contentCardMap
                   : (NSDictionary *)contentCardMap);
 
+
+RCT_EXTERN_METHOD(handleJavascriptMessage
+                  : (NSString *)messageId handlerName
+                  : (NSString *)handlerName)
+
 RCT_EXTERN_METHOD(trackPropositionItem
                   : (NSString *)uuid interaction
                   : (NSString * _Nullable)interaction eventType
diff --git a/packages/messaging/ios/src/RCTAEPMessaging.swift b/packages/messaging/ios/src/RCTAEPMessaging.swift
index 3629a1a38..ee66f5385 100644
--- a/packages/messaging/ios/src/RCTAEPMessaging.swift
+++ b/packages/messaging/ios/src/RCTAEPMessaging.swift
@@ -21,6 +21,7 @@ import WebKit
 @objc(RCTAEPMessaging)
 public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
     private var messageCache = [String: Message]()
+    private var jsHandlerMessageCache = [String: Message]()
     private var latestMessage: Message? = nil
     private let semaphore = DispatchSemaphore(value: 0)
     private var shouldSaveMessage = false
@@ -263,6 +264,28 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         }
     }
 
+    @objc
+    func handleJavascriptMessage(
+        _ messageId: String,
+        handlerName: String
+    ) {
+        guard let message = jsHandlerMessageCache[messageId] else { 
+            print("[RCTAEPMessaging] handleJavascriptMessage: No message found in cache for messageId: \(messageId)")
+            return 
+        }
+
+        message.handleJavascriptMessage(handlerName) { [weak self] content in
+            self?.emitNativeEvent(
+                name: Constants.ON_JAVASCRIPT_MESSAGE_EVENT,
+                body: [
+                    Constants.MESSAGE_ID_KEY: messageId,
+                    Constants.HANDLER_NAME_KEY: handlerName,
+                    Constants.CONTENT_KEY: content ?? ""
+                ]
+            )
+        }
+    }
+
     /// MARK: - Unified PropositionItem Tracking Methods
     
     /**
@@ -329,6 +352,7 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         if let fullscreenMessage = message as? FullscreenMessage,
             let parentMessage = fullscreenMessage.parent
         {
+            jsHandlerMessageCache.removeValue(forKey: parentMessage.id)
             emitNativeEvent(
                 name: Constants.ON_DISMISS_EVENT,
                 body: RCTAEPMessagingDataBridge.transformToMessage(
@@ -342,6 +366,7 @@ public class RCTAEPMessaging: RCTEventEmitter, MessagingDelegate {
         if let fullscreenMessage = message as? FullscreenMessage,
             let message = fullscreenMessage.parent
         {
+            jsHandlerMessageCache[message.id] = message
             emitNativeEvent(
                 name: Constants.ON_SHOW_EVENT,
                 body: RCTAEPMessagingDataBridge.transformToMessage(message: message)
diff --git a/packages/messaging/ios/src/RCTAEPMessagingConstants.swift b/packages/messaging/ios/src/RCTAEPMessagingConstants.swift
index 9b662d434..64f26aa03 100644
--- a/packages/messaging/ios/src/RCTAEPMessagingConstants.swift
+++ b/packages/messaging/ios/src/RCTAEPMessagingConstants.swift
@@ -16,7 +16,11 @@ class Constants {
     static let ON_SHOW_EVENT = "onShow"
     static let SHOULD_SHOW_MESSAGE_EVENT = "shouldShowMessage"
     static let URL_LOADED_EVENT = "urlLoaded"
+    static let ON_JAVASCRIPT_MESSAGE_EVENT = "onJavascriptMessage"
     static let SUPPORTED_EVENTS = [
-        ON_DISMISS_EVENT, ON_SHOW_EVENT, SHOULD_SHOW_MESSAGE_EVENT, URL_LOADED_EVENT,
+        ON_DISMISS_EVENT, ON_SHOW_EVENT, SHOULD_SHOW_MESSAGE_EVENT, URL_LOADED_EVENT, ON_JAVASCRIPT_MESSAGE_EVENT
     ]
+    static let MESSAGE_ID_KEY = "messageId"
+    static let HANDLER_NAME_KEY = "handlerName"
+    static let CONTENT_KEY = "content"
 }
diff --git a/packages/messaging/src/Messaging.ts b/packages/messaging/src/Messaging.ts
index 34100d757..8a171efed 100644
--- a/packages/messaging/src/Messaging.ts
+++ b/packages/messaging/src/Messaging.ts
@@ -129,31 +129,33 @@ class Messaging {
 
     const eventEmitter = new NativeEventEmitter(RCTAEPMessaging);
 
-    eventEmitter.addListener('onShow', (message) =>
-      messagingDelegate?.onShow?.(message)
+    eventEmitter.addListener('onShow', (message: Message) =>
+      messagingDelegate?.onShow?.(new Message(message))
     );
 
-    eventEmitter.addListener('onDismiss', (message) => {
-      messagingDelegate?.onDismiss?.(message);
+    eventEmitter.addListener('onDismiss', (message: Message) => {
+      message._clearJavascriptMessageHandlers();
+      messagingDelegate?.onDismiss?.(new Message(message));
     });
 
-    eventEmitter.addListener('shouldShowMessage', (message) => {
+    eventEmitter.addListener('shouldShowMessage', (message: Message) => {
+      const messageInstance = new Message(message);
       const shouldShowMessage =
-        messagingDelegate?.shouldShowMessage?.(message) ?? true;
+        messagingDelegate?.shouldShowMessage?.(messageInstance) ?? true;
       const shouldSaveMessage =
-        messagingDelegate?.shouldSaveMessage?.(message) ?? false;
+        messagingDelegate?.shouldSaveMessage?.(messageInstance) ?? false;
       RCTAEPMessaging.setMessageSettings(shouldShowMessage, shouldSaveMessage);
     });
 
     if (Platform.OS === 'ios') {
-      eventEmitter.addListener('urlLoaded', (event) =>
-        messagingDelegate?.urlLoaded?.(event.url, event.message)
+      eventEmitter.addListener('urlLoaded', (event: {url: string, message: Message}) =>
+        messagingDelegate?.urlLoaded?.(event.url, new Message(event.message))
       );
     }
 
     if (Platform.OS === 'android') {
-      eventEmitter.addListener('onContentLoaded', (event) =>
-        messagingDelegate?.onContentLoaded?.(event.message)
+      eventEmitter.addListener('onContentLoaded', (event: {message: Message}) =>
+        messagingDelegate?.onContentLoaded?.(new Message(event.message))
       );
     }
 
diff --git a/packages/messaging/src/models/Message.ts b/packages/messaging/src/models/Message.ts
index bee749d30..458c7c69f 100644
--- a/packages/messaging/src/models/Message.ts
+++ b/packages/messaging/src/models/Message.ts
@@ -10,9 +10,23 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
-import { NativeModules } from 'react-native';
+import { NativeEventEmitter, NativeModules } from 'react-native';
+
 const RCTAEPMessaging = NativeModules.AEPMessaging;
 
+// Registery to store inAppMessage callbacks for each message in Message.handleJavascriptMessage
+// Record - {messageId : {handlerName : callback}}
+const jsMessageHandlers: Record<string, Record<string, (content: string) => void>> = {};
+const handleJSMessageEventEmitter = new NativeEventEmitter(RCTAEPMessaging);
+
+// invokes the callback registered in Message.handleJavascriptMessage with the content received from the inAppMessage webview
+handleJSMessageEventEmitter.addListener('onJavascriptMessage', (event) => {
+  const {messageId, handlerName, content} = event;
+  if (jsMessageHandlers[messageId] && jsMessageHandlers[messageId][handlerName]) {
+    jsMessageHandlers[messageId][handlerName](content);
+  }
+});
+
 class Message {
   id: string;
   autoTrack: boolean;
@@ -67,6 +81,42 @@ class Message {
   clear() {
     RCTAEPMessaging.clear(this.id);
   }
+
+  /**
+   * Adds a handler for named JavaScript messages sent from the message's WebView.
+   * The parameter passed to handler will contain the body of the message passed from the WebView's JavaScript.
+   * @param {string} handlerName: The name of the message that should be handled by the handler
+   * @param {function} handler: The method or closure to be called with the body of the message created in the Message's JavaScript
+   */
+  handleJavascriptMessage(handlerName: string, handler: (content: string) => void) {
+    // Validate parameters
+    if (!handlerName) {
+      console.warn('[AEP Messaging] handleJavascriptMessage: handlerName is required');
+      return;
+    }
+
+    if (typeof handler !== 'function') {
+      console.warn('[AEP Messaging] handleJavascriptMessage: handler must be a function');
+      return;
+    }
+
+    // cache the callback
+    if (!jsMessageHandlers[this.id]) {
+      jsMessageHandlers[this.id] = {};
+    }
+    jsMessageHandlers[this.id][handlerName] = handler;
+    RCTAEPMessaging.handleJavascriptMessage(this.id, handlerName);
+  }
+
+  /**
+   * @internal - For internal use only.
+   * Clears all the javascript message handlers for the message.
+   * This function must be called if the callbacks registered in handleJavascriptMessage are no longer needed.
+   * Failure to call this function may lead to memory leaks.
+   */
+  _clearJavascriptMessageHandlers() {
+    delete jsMessageHandlers[this.id];
+  }
 }
 
 export default Message;
diff --git a/packages/messaging/tutorials/In-App Messaging.md b/packages/messaging/tutorials/In-App Messaging.md
new file mode 100644
index 000000000..4ab8ca78a
--- /dev/null
+++ b/packages/messaging/tutorials/In-App Messaging.md	
@@ -0,0 +1,67 @@
+# Native handling of JavaScript events
+
+You can handle events from in-app message interactions natively within your application by completing the following steps:
+- [Implement and assign a `Messaging Delegate`](#implement-and-assign-a-messaging-delegate)
+- [Register a JavaScript handler for your In-App Message](#register-a-javascript-handler-for-your-in-app-message)
+- [Post the JavaScript message from your In-App Message](#post-the-javascript-message-from-your-in-app-message)
+
+## Implement and assign a `Messaging Delegate`
+
+To register a JavaScript event handler with a Message object, you will first need to implement and set a MessagingDelegate.
+Please read the [documentation](../README.md/#programmatically-control-the-display-of-in-app-messages) for more detailed instructions on implementing and using a MessagingDelegate.
+
+## Register a JavaScript handler for your In-App Message
+
+In the `onShow` function of `MessagingDelegate`, call `handleJavascriptMessage(handlerName: string, handler: (content: string) => void)` to register your handler.
+
+The name of the message you intend to pass from the JavaScript side should be specified in the first parameter.
+
+### Example
+
+```typescript
+Messaging.setMessagingDelegate({
+    onShow: msg => {
+      console.log('show', msg);
+      msg.handleJavascriptMessage(
+        'myInappCallback',
+        (content) => {
+          console.log('Received webview content:', content);
+        }
+      );
+    }
+  });
+```
+
+## Post the JavaScript message from your In-App Message
+
+Now that the in-app message has been displayed, the final step is to post the JavaScript message.
+
+Continuing from the previous example, the developer is going to post the `myInappCallback` message from their HTML, which will in turn call the handler previously configured:
+
+```html
+<html>
+    <head>
+        <script type="text/javascript">
+            function callNative(action) {
+                try {
+                    // the name of the message handler is the same name that must be registered in  react native code.
+                    // in this case the message name is "myInappCallback"
+                    webkit.messageHandlers.myInappCallback.postMessage(action);
+                } catch(err) {
+                    console.log('The native context does not exist yet'); }
+                }
+            </script>
+    </head>
+    <body>
+        <button onclick="callNative('callbacks are cool!')">Native callback!</button>
+    </body>
+</html>
+```
+
+Note: (The above HTML is not representative of a valid in-app message, and is intended only to demonstrate how to post the JavaScript message).
+
+When the user clicks the button inside of this in-app message, the handler configured in the previous step will be called. The handler will send an Experience Event tracking the interaction, and print the following message to the console:
+
+```bash
+JavaScript body passed to react native callback: callbacks are cool!
+```

From 0872dc68dd453d46374ab67e6e1143657b6db1b5 Mon Sep 17 00:00:00 2001
From: Ishita Gambhir <igambhir@adobe.com>
Date: Wed, 3 Sep 2025 14:17:22 +0530
Subject: [PATCH 3/3] messaging version bump for 7.2.0 release (#526)

---
 packages/messaging/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/messaging/package.json b/packages/messaging/package.json
index 0521a10ec..ab433604d 100644
--- a/packages/messaging/package.json
+++ b/packages/messaging/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@adobe/react-native-aepmessaging",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "Adobe Experience Platform support for React Native apps.",
   "homepage": "https://developer.adobe.com/client-sdks/documentation/",
   "license": "Apache-2.0",