@adobe/react-native-aepmessaging 7.1.1 → 7.2.0

package/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.
+   */
   static trackContentCardDisplay(proposition: MessagingProposition, contentCard: ContentCard): void {
     RCTAEPMessaging.trackContentCardDisplay(proposition, contentCard);
   }
 
+  /**
+   * @deprecated Use PropositionItem.track(...) instead.
+   */
   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
@@ -110,31 +129,34 @@ 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) => {
+      const messageInstance = new Message(message);
+      messageInstance._clearJavascriptMessageHandlers();
+      messagingDelegate?.onDismiss?.(messageInstance);
     });
 
-    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))
       );
     }
 

package/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,
 };

package/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;
+  }
+
+}

package/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;
+	}
+}

package/src/models/{JSONPropositionItem.ts → 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;
+	}
+}

package/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;

package/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 };

package/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;

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

package/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!
+```

package/dist/models/JSONPropositionItem.d.ts

@@ -1,8 +0,0 @@
-import { PersonalizationSchema } from './PersonalizationSchema';
-export interface JSONPropositionItem {
-    id: string;
-    data: {
-        content: string;
-    };
-    schema: PersonalizationSchema.JSON_CONTENT;
-}

package/dist/models/JSONPropositionItem.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"JSONPropositionItem.js","sourceRoot":"","sources":["../../src/models/JSONPropositionItem.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;EAUE"}