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 <[email protected]>

Author: namArora3112

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,14 +103,35 @@ 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);
         }
       }
     }
   }
 }
 
+
+// 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>
   );

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**

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
+    );
+  });
+});
+
+