Embedded msg (#232)

* Embedded Manager Module - WIP

* Embedded Manager Module - added uuid library

* Code modified for embedded msg

* Documentation added

* Events example added

* Embedded msg configurations changed

* Import issue of embeddedManager fixed

* Circuler dependency solved

* Linting error fixing

* events code break down into separate folders

* Import issues fixed

---------

Co-authored-by: Vishal Joshi <[email protected]>

EmbeddedManagerDoc.md

@@ -0,0 +1,256 @@
+# EmbeddedMessageManager Class
+The `EmbeddedManager` class is a fundamental component of the Web SDK project that facilitates the seamless integration and management of embedded messages 
+and interactions within web applications. It offers developers a set of methods and functionalities to efficiently handle messages sent from external sources 
+and provides mechanisms to respond to updates and actions associated with these messages.
+
+Key Features and Functionalities:
+
+- Message Synchronization: Developers can utilize the syncMessages method to synchronize messages for a specific user. Upon synchronization, a provided callback function is invoked, allowing developers to take actions based on the synchronized messages.
+- Listeners: The class allows developers to register listeners using the addUpdateListener and addActionHandler methods. These listeners enable the application to respond to updates and actions related to embedded messages.
+- Handlers Retrieval: The class offers methods to retrieve arrays of registered update and action handlers using getUpdateHandlers and getActionHandlers, respectively. This enables developers to manage and interact with these handlers as needed.
+
+Properties
+- messages: IEmbeddedMessage[]: An array that holds the embedded messages received.
+
+### Table of Contents
+- [Syncing Messages](#syncing-messages)
+- [Adding Listeners](#adding-listeners)
+- [Retrieving Action Handlers](#retrieving-action-handlers)
+- [Retrieving Update Handlers](#retrieving-update-handlers)
+
+# Usage
+
+1. `Syncing Messages`
+The EmbeddedManager class provides a method to sync messages for a specific user and invoke a callback upon synchronization.
+public async syncMessages(userId: string, callback: () => void): Promise<void>
+
+Params
+- userId: The identifier of the user for whom to sync messages.
+- callback: A function to be called after message synchronization is complete.
+
+```ts
+import { EmbeddedManager } from '@iterable/web-sdk';
+
+await new EmbeddedManager().syncMessages('harrymash2006', () => console.log('Synced message'));
+```
+
+2. `Adding Listeners`
+Developers can register listeners to handle updates and actions related to embedded messages.
+public addUpdateListener(updateListener: EmbeddedMessageUpdateHandler): void
+public addActionHandler(actionHandler: EmbeddedMessageActionHandler): void
+
+- updateListener: A listener that implements the EmbeddedMessageUpdateHandler interface to handle message update events.
+- actionHandler: A listener that implements the EmbeddedMessageActionHandler interface to handle message action events.
+
+3. `Retrieving Action Handlers`
+This method retrieves an array of registered action handlers.
+public getActionHandlers(): Array<EmbeddedMessageActionHandler>
+
+4. `Retrieving Update Handlers`
+This method retrieves an array of registered update handlers.
+public getUpdateHandlers(): Array<EmbeddedMessageUpdateHandler>
+
+Private Methods
+- The following are private methods used internally by the class:
+
+- retrieveEmbeddedMessages(userId: string): Retrieves embedded messages for the specified user.
+- setMessages(_processor: EmbeddedMessagingProcessor): Sets the internal messages array based on the provided processor.
+- trackNewlyRetrieved(_processor: EmbeddedMessagingProcessor): Tracks newly retrieved messages and invokes tracking methods.
+- notifyUpdateDelegates(): Notifies registered update listeners of message updates.
+- notifyDelegatesOfInvalidApiKeyOrSyncStop(): Notifies listeners when the API key is invalid or synchronization stops.
+
+# EmbeddedSessionManager Class
+
+The `EmbeddedSessionManager` class is a core component of the Web SDK project designed to manage user interactions with embedded messages in web applications. This class offers developers a range of functions to track and analyze user sessions, impressions, and engagement with embedded messages. It provides methods to start and end sessions, track impressions for individual messages, and retrieve impression data. By utilizing these functionalities, developers can gain insights into how users engage with embedded messages, enabling them to optimize user experiences and measure the effectiveness of message content.
+
+Properties
+- impressions: Map<string, IEmbeddedImpression>: A map that holds impression data for embedded messages.
+- session: IEmbeddedSession: An object representing the current embedded session.
+
+### Table of Contents
+- [Checking Tracking Status](#checking-tracking-status)
+- [Starting a Session](#starting-a-session)
+- [Ending a Session](#ending-a-session)
+- [Managing Impressions](#managing-impressions)
+
+# Usage
+
+1. `Checking Tracking Status`
+The EmbeddedSessionManager class provides a method to check if session tracking is active.
+
+```ts
+public isTracking(): boolean
+```
+Returns true if tracking is active, otherwise false.
+
+2. `Starting a Session`
+    Developers can start a new embedded session using the startSession method.
+
+```ts
+public startSession(): void
+```
+This method initializes a new session, provided that tracking is not already active.
+
+3. `Ending a Session`
+The class offers the endSession method to end the current session and track impression data.
+
+```ts
+public async endSession(): Promise<void>
+```
+This method finalizes the session, collects impression data, and triggers the tracking of the session if applicable.
+
+4. `Managing Impressions`
+- startImpression(messageId: string): Starts tracking an impression for a specific message.
+The startImpression function initiates the tracking of an impression associated with a specific message. Impressions provide insights into how users engage with embedded messages, allowing developers to measure their effectiveness.
+
+    When a message's impression tracking starts, the following steps are taken:
+
+    - The function accepts a messageId parameter, which uniquely identifies the message for which the impression is being tracked.
+    - If an impression for the provided messageId already exists in the impressions map, the function updates the existing impression's start time to the current date and time.
+    - If an impression for the provided messageId does not exist, a new EmbeddedImpressionData object is created, representing the impression. This object's start time is set to the current date and time, and it is added to the impressions map with the messageId as the key.
+
+- pauseImpression(messageId: string): Pauses tracking for an impression associated with a message.
+The pauseImpression function temporarily halts the tracking of an ongoing impression associated with a particular message. Pausing impressions allows developers to accurately measure how long users engage with a message before taking actions.
+
+    When an impression's tracking is paused, the following actions occur:
+
+    - The function receives a messageId parameter, identifying the message whose impression tracking needs to be paused.
+    - The function checks if an impression with the given messageId exists in the impressions map.
+        - If an impression is found, its start time is used to calculate the duration of engagement for the impression.
+        - The impression's displayCount is incremented to keep track of the number of times the impression has been displayed.
+        - The calculated duration is added to the impression's duration value, indicating the total time users have spent engaging with the message.
+        - The impression's start time is reset to undefined, effectively pausing the tracking of the current engagement.
+
+- endAllImpressions(): Ends tracking for all impressions.
+The endAllImpressions function concludes the tracking of all ongoing impressions. It ensures that all impressions are accurately measured and finalized before ending an embedded session.
+
+    When all impressions are ended:
+
+    - The function iterates through all impressions stored in the impressions map.
+    - For each impression, the same calculation and updates performed in the pauseImpression function are applied, effectively finalizing the impression's engagement duration and display count.
+    - After iterating through all impressions, the impressions map is cleared, removing all impression data.
+
+- getImpressionList(): Retrieves a list of tracked impressions.
+The getImpressionList function retrieves a list of tracked impressions, including their associated metadata. This function is essential for reporting and analyzing user engagement with embedded messages.
+
+    When calling getImpressionList:
+
+    - The function initializes an empty array to hold the list of impressions.
+    - It iterates through all impressions stored in the impressions map.
+    - For each impression, an EmbeddedImpressionData object is created, containing the messageId, displayCount, and duration of the impression. This object is added to the array.
+    - Once all impressions have been processed, the array of impression data is returned.
+
+# Tracking Function
+
+1. `trackEmbeddedMessageReceived(payload: IEmbeddedMessage)`
+The tracking function `trackEmbeddedMessageReceived` enables developers to track received embedded messages and send relevant data to the server for analysis.
+
+- Parameters
+  - payload: IEmbeddedMessage: The payload representing the received embedded message.
+- Return Value
+  - The function returns a promise containing the result of the tracking request, which is a part of the baseIterableRequest function.
+- Behavior
+  - The function constructs a POST request to the server endpoint /embedded-messaging/events/received.
+  - It packages the received embedded message data in the request payload.
+  - The function performs validation of the request payload using the trackEmbeddedMessageSchema schema.
+  - The request is sent to the server for analysis.
+- Example
+```ts
+const receivedMessage = {
+  metadata: {
+    messageId: 'abc123',
+    campaignId: 1,
+  },
+  elements: {
+    title: 'Welcome Message',
+    body: 'Thank you for using our app!',
+  },
+};
+
+trackEmbeddedMessageReceived(receivedMessage)
+  .then(response => {
+    console.log('Message reception tracked:', response);
+  })
+  .catch(error => {
+    console.error('Error tracking message reception:', error);
+  });
+```
+
+2. `trackEmbeddedMessageClick(payload: IEmbeddedMessageMetadata, buttonIdentifier: string, clickedUrl: string, appPackageName: string)`
+The tracking function `trackEmbeddedMessageClick` enables developers to track user clicks on buttons within embedded messages. And it's also enables developers to collect and analyze user interaction data to improve engagement and measure the effectiveness of message content.
+
+- Parameters
+  - payload: IEmbeddedMessageMetadata: Metadata associated with the embedded message.
+  - buttonIdentifier: string: Unique identifier for the clicked button.
+  - clickedUrl: string: The URL associated with the clicked button.
+  - appPackageName: string: The package name of the application.
+- Return Value
+  - The function returns a promise containing the result of the tracking request, which is a part of the baseIterableRequest function.
+- Behavior
+  - The function constructs a POST request to the server endpoint /embedded-messaging/events/click.
+  - It packages the following data in the request payload:
+    - messageId: The unique identifier of the embedded message.
+    - buttonIdentifier: The identifier of the clicked button.
+    - targetUrl: The URL associated with the clicked button.
+    - deviceInfo: An object containing the package name of the application.
+  - The function performs validation of the request payload using the trackEmbeddedMessageClickSchema schema.
+  - The request is sent to the server for analysis.
+- Example
+```ts
+const payload = {
+  messageId: 'abc123',
+  campaignId: 1,
+};
+
+const buttonIdentifier = 'button-123';
+const clickedUrl = 'https://example.com';
+const appPackageName = 'com.example.app';
+
+trackEmbeddedMessageClick(payload, buttonIdentifier, clickedUrl, appPackageName)
+  .then(response => {
+    console.log('Click tracking successful:', response);
+  })
+  .catch(error => {
+    console.error('Error tracking click:', error);
+  });
+```
+
+3. `trackEmbeddedSession(payload: IEmbeddedSession)`
+The tracking function `trackEmbeddedSession` enables developers to track impressions and user sessions associated with embedded messages. The function facilitates data collection for analysis and insights into user engagement patterns.
+
+- Parameters
+  - payload: IEmbeddedSession: The payload representing the session to be tracked.
+- Return Value
+  - The function returns a promise containing the result of the tracking request, which is a part of the baseIterableRequest function.
+- Behavior
+  - The function constructs a POST request to the server endpoint /embedded-messaging/events/impression.
+  - It packages the session data in the request payload.
+  - The function performs validation of the request payload using the trackEmbeddedSessionSchema schema.
+  - The request is sent to the server for analysis.
+- Example
+```ts
+const sessionData = {
+  start: new Date(),
+  end: new Date(),
+  impressions: [
+    {
+      messageId: 'abc123',
+      displayCount: 3,
+      duration: 10,
+    },
+    {
+      messageId: 'def456',
+      displayCount: 2,
+      duration: 8,
+    },
+  ],
+};
+
+trackEmbeddedSession(sessionData)
+  .then(response => {
+    console.log('Session tracking successful:', response);
+  })
+  .catch(error => {
+    console.error('Error tracking session:', error);
+  });
+```

package.json

@@ -38,6 +38,7 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "throttle-debounce": "^3.0.1",
+    "uuid": "^9.0.0",
     "yup": "^0.32.9"
   },
   "scripts": {
@@ -71,6 +72,7 @@
     "@types/react": "^18.2.21",
     "@types/react-dom": "^18.2.7",
     "@types/throttle-debounce": "^2.1.0",
+    "@types/uuid": "^9.0.2",
     "@typescript-eslint/eslint-plugin": "^5.38.1",
     "@typescript-eslint/parser": "^5.38.1",
     "@webpack-cli/serve": "^1.6.0",

react-example/src/index.tsx

@@ -8,6 +8,7 @@ import Commerce from 'src/views/Commerce';
 import Events from 'src/views/Events';
 import Users from 'src/views/Users';
 import InApp from 'src/views/InApp';
+import EmbeddedMessage from 'src/views/Embedded';
 import { BrowserRouter, Routes, Route } from 'react-router-dom';
 import Link from 'src/components/Link';
 import styled from 'styled-components';
@@ -82,6 +83,7 @@ const HomeLink = styled(Link)`
               <Route path="/events" element={<Events />} />
               <Route path="/users" element={<Users />} />
               <Route path="/inApp" element={<InApp />} />
+              <Route path="/embedded" element={<EmbeddedMessage />} />
             </Routes>
           </RouteWrapper>
         </UserProvider>