[SDK-387] automatically start and end sessions

example/src/components/Embedded/Embedded.styles.ts

@@ -21,10 +21,8 @@ const styles = StyleSheet.create({
   buttonText,
   container,
   embeddedSection: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 16,
-    paddingHorizontal: 16,
+
+    marginBottom: 16,
   },
   hr,
   inputContainer: {

example/src/components/Embedded/Embedded.tsx

@@ -1,3 +1,4 @@
+import { useCallback, useState } from 'react';
 import {
   Alert,
   Modal,
@@ -7,15 +8,16 @@ import {
   TouchableOpacity,
   View,
 } from 'react-native';
-import { useCallback, useState } from 'react';
+import { SafeAreaView } from 'react-native-safe-area-context';
+
 import {
+  EmbeddedSessionManager,
   Iterable,
-  type IterableEmbeddedMessage,
-  type IterableEmbeddedViewConfig,
   IterableEmbeddedView,
   IterableEmbeddedViewType,
+  type IterableEmbeddedMessage,
+  type IterableEmbeddedViewConfig,
 } from '@iterable/react-native-sdk';
-import { SafeAreaView } from 'react-native-safe-area-context';
 
 import styles from './Embedded.styles';
 
@@ -44,18 +46,6 @@ export const Embedded = () => {
 
   const idsToFetch = parsedPlacementIds.length > 0 ? parsedPlacementIds : null;
 
-  const syncEmbeddedMessages = useCallback(() => {
-    Iterable.embeddedManager.syncMessages();
-  }, []);
-
-  const startEmbeddedSession = useCallback(() => {
-    Iterable.embeddedManager.startSession();
-  }, []);
-
-  const endEmbeddedSession = useCallback(() => {
-    Iterable.embeddedManager.endSession();
-  }, []);
-
   const getEmbeddedMessages = useCallback(() => {
     Iterable.embeddedManager
       .getMessages(idsToFetch)
@@ -97,9 +87,6 @@ export const Embedded = () => {
           </Text>
         </View>
       )}
-      <Text style={styles.subtitle}>
-        Enter placement IDs to fetch embedded messages
-      </Text>
       <View style={styles.utilitySection}>
         <View style={styles.viewTypeSelector}>
           <Text style={styles.text}>Select View Type:</Text>
@@ -164,15 +151,6 @@ export const Embedded = () => {
             </TouchableOpacity>
           </View>
         </View>
-        <TouchableOpacity style={styles.button} onPress={syncEmbeddedMessages}>
-          <Text style={styles.buttonText}>Sync messages</Text>
-        </TouchableOpacity>
-        <TouchableOpacity style={styles.button} onPress={startEmbeddedSession}>
-          <Text style={styles.buttonText}>Start session</Text>
-        </TouchableOpacity>
-        <TouchableOpacity style={styles.button} onPress={endEmbeddedSession}>
-          <Text style={styles.buttonText}>End session</Text>
-        </TouchableOpacity>
         <TouchableOpacity style={styles.button} onPress={openConfigEditor}>
           <Text style={styles.buttonText}>Set view config</Text>
         </TouchableOpacity>
@@ -229,16 +207,20 @@ export const Embedded = () => {
       </Modal>
       <View style={styles.hr} />
       <ScrollView>
-        <View style={styles.embeddedSection}>
+        <EmbeddedSessionManager>
           {embeddedMessages.map((message) => (
-            <IterableEmbeddedView
+            <View
+              style={styles.embeddedSection}
               key={message.metadata.messageId}
-              viewType={selectedViewType}
-              message={message}
-              config={viewConfig}
-            />
+            >
+              <IterableEmbeddedView
+                viewType={selectedViewType}
+                message={message}
+                config={viewConfig}
+              />
+            </View>
           ))}
-        </View>
+        </EmbeddedSessionManager>
       </ScrollView>
     </SafeAreaView>
   );

src/embedded/components/EmbeddedSessionDevWarning/EmbeddedSessionDevWarning.styles.ts

@@ -0,0 +1,23 @@
+import { StyleSheet } from 'react-native';
+
+const ERROR_BANNER_BACKGROUND = '#FEF2F2';
+const ERROR_BANNER_BORDER = '#FECACA';
+const ERROR_BANNER_TEXT = '#991B1B';
+
+export const styles = StyleSheet.create({
+  banner: {
+    alignSelf: 'stretch',
+    backgroundColor: ERROR_BANNER_BACKGROUND,
+    borderColor: ERROR_BANNER_BORDER,
+    borderWidth: 1,
+    marginBottom: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+  },
+  text: {
+    color: ERROR_BANNER_TEXT,
+    fontSize: 12,
+    fontWeight: '600',
+    lineHeight: 16,
+  },
+});

src/embedded/components/EmbeddedSessionDevWarning/EmbeddedSessionDevWarning.test.tsx

@@ -0,0 +1,20 @@
+import { render } from '@testing-library/react-native';
+
+import { EmbeddedSessionDevWarning } from './EmbeddedSessionDevWarning';
+
+describe('EmbeddedSessionDevWarning', () => {
+  it('renders nothing when not visible', () => {
+    const { queryByRole } = render(
+      <EmbeddedSessionDevWarning visible={false} componentName="X" />
+    );
+    expect(queryByRole('alert')).toBeNull();
+  });
+
+  it('renders warning text when visible', () => {
+    const { getByText } = render(
+      <EmbeddedSessionDevWarning visible componentName="IterableEmbeddedBanner" />
+    );
+    expect(getByText(/IterableEmbeddedBanner/)).toBeTruthy();
+    expect(getByText(/EmbeddedSessionManager/)).toBeTruthy();
+  });
+});

src/embedded/components/EmbeddedSessionDevWarning/EmbeddedSessionDevWarning.tsx

@@ -0,0 +1,35 @@
+import { Text, View } from 'react-native';
+
+import { styles } from './EmbeddedSessionDevWarning.styles';
+
+interface EmbeddedSessionDevWarningProps {
+  /** When true, shows the dev-only banner. */
+  visible: boolean;
+  /** Name of the component (for the message). */
+  componentName: string;
+}
+
+/**
+ * Dev-only error-styled banner when embedded views are not wrapped in
+ * `EmbeddedSessionManager`.
+ */
+export const EmbeddedSessionDevWarning = ({
+  visible,
+  componentName,
+}: EmbeddedSessionDevWarningProps) => {
+  if (!visible) {
+    return null;
+  }
+
+  const message = `[Iterable] ${componentName}: wrap this view in <EmbeddedSessionManager> so embedded session tracking works correctly.`;
+
+  return (
+    <View
+      style={styles.banner}
+      accessibilityRole="alert"
+      accessibilityLiveRegion="assertive"
+    >
+      <Text style={styles.text}>{message}</Text>
+    </View>
+  );
+};

src/embedded/components/EmbeddedSessionManager.test.tsx

@@ -0,0 +1,58 @@
+import { render } from '@testing-library/react-native';
+import { Text } from 'react-native';
+
+import { Iterable } from '../../core/classes/Iterable';
+import { EmbeddedSessionManager } from './EmbeddedSessionManager';
+
+describe('EmbeddedSessionManager', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(Iterable.embeddedManager, 'startSession').mockImplementation(
+      () => {}
+    );
+    jest.spyOn(Iterable.embeddedManager, 'endSession').mockImplementation(
+      () => {}
+    );
+  });
+
+  it('renders its children', () => {
+    const { getByTestId } = render(
+      <EmbeddedSessionManager>
+        <Text testID="embedded-child">hello</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(getByTestId('embedded-child')).toBeTruthy();
+  });
+
+  it('starts session on mount and ends session on unmount', () => {
+    const { unmount } = render(
+      <EmbeddedSessionManager>
+        <Text>child</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.startSession).toHaveBeenCalledTimes(1);
+    expect(Iterable.embeddedManager.endSession).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(Iterable.embeddedManager.endSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not double track session for nested wrappers', () => {
+    const { unmount } = render(
+      <EmbeddedSessionManager>
+        <EmbeddedSessionManager>
+          <Text>nested child</Text>
+        </EmbeddedSessionManager>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.startSession).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    expect(Iterable.embeddedManager.endSession).toHaveBeenCalledTimes(1);
+  });
+});

src/embedded/components/EmbeddedSessionManager.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import { useContext, useEffect } from 'react';
+import { View } from 'react-native';
+import type { ViewProps } from 'react-native';
+
+import { Iterable } from '../../core/classes/Iterable';
+import { EmbeddedSessionContext } from '../context/EmbeddedSessionContext';
+
+interface EmbeddedSessionManagerProps extends ViewProps {
+  children?: ReactNode;
+}
+
+/**
+ * Wraps embedded content and tracks an embedded session for its lifecycle.
+ *
+ * If nested, only the top-most wrapper starts and ends the session.
+ */
+export const EmbeddedSessionManager = ({
+  children,
+  ...viewProps
+}: EmbeddedSessionManagerProps) => {
+  const hasActiveParentSession = useContext(EmbeddedSessionContext);
+
+  useEffect(() => {
+    if (hasActiveParentSession) {
+      return;
+    }
+
+    Iterable.embeddedManager.syncMessages();
+    Iterable.embeddedManager.startSession();
+
+    return () => {
+      Iterable.embeddedManager.endSession();
+    };
+  }, [hasActiveParentSession]);
+
+  return (
+    <EmbeddedSessionContext.Provider value={true}>
+      <View {...viewProps}>{children}</View>
+    </EmbeddedSessionContext.Provider>
+  );
+};

src/embedded/components/IterableEmbeddedBanner/IterableEmbeddedBanner.test.tsx

@@ -14,6 +14,10 @@ jest.mock('../../hooks/useEmbeddedView', () => ({
   useEmbeddedView: jest.fn(),
 }));
 
+jest.mock('../../hooks/useWarnIfOutsideEmbeddedSession', () => ({
+  useWarnIfOutsideEmbeddedSession: jest.fn(),
+}));
+
 const mockUseEmbeddedView = useEmbeddedView as jest.MockedFunction<
   typeof useEmbeddedView
 >;

src/embedded/components/IterableEmbeddedBanner/IterableEmbeddedBanner.tsx

@@ -11,13 +11,17 @@ import {
 
 import { IterableEmbeddedViewType } from '../../enums';
 import { useEmbeddedView } from '../../hooks/useEmbeddedView';
+import { useWarnIfOutsideEmbeddedSession } from '../../hooks/useWarnIfOutsideEmbeddedSession';
 import type { IterableEmbeddedComponentProps } from '../../types/IterableEmbeddedComponentProps';
+import { EmbeddedSessionDevWarning } from '../EmbeddedSessionDevWarning/EmbeddedSessionDevWarning';
 import {
   styles,
   IMAGE_HEIGHT,
   IMAGE_WIDTH,
 } from './IterableEmbeddedBanner.styles';
 
+const COMPONENT_NAME = 'IterableEmbeddedBanner';
+
 /**
  * TODO: figure out how default action works.
  */
@@ -28,6 +32,9 @@ export const IterableEmbeddedBanner = ({
   onButtonClick,
   onMessageClick,
 }: IterableEmbeddedComponentProps) => {
+  const showEmbeddedSessionWarning =
+    useWarnIfOutsideEmbeddedSession(COMPONENT_NAME);
+
   const { parsedStyles, media, handleButtonClick, handleMessageClick } =
     useEmbeddedView(IterableEmbeddedViewType.Banner, {
       message,
@@ -38,6 +45,12 @@ export const IterableEmbeddedBanner = ({
 
   const buttons = message.elements?.buttons ?? [];
 
+  if (showEmbeddedSessionWarning) {
+    return (
+      <EmbeddedSessionDevWarning visible componentName={COMPONENT_NAME} />
+    );
+  }
+
   return (
     <Pressable onPress={handleMessageClick}>
       <View

src/embedded/components/IterableEmbeddedCard/IterableEmbeddedCard.test.tsx

@@ -20,6 +20,10 @@ jest.mock('../../hooks/useEmbeddedView', () => ({
   useEmbeddedView: jest.fn(),
 }));
 
+jest.mock('../../hooks/useWarnIfOutsideEmbeddedSession', () => ({
+  useWarnIfOutsideEmbeddedSession: jest.fn(),
+}));
+
 const mockUseEmbeddedView = useEmbeddedView as jest.MockedFunction<
   typeof useEmbeddedView
 >;

src/embedded/components/IterableEmbeddedCard/IterableEmbeddedCard.tsx

@@ -12,9 +12,13 @@ import {
 import { IterableLogoGrey } from '../../../core/assets';
 import { IterableEmbeddedViewType } from '../../enums';
 import { useEmbeddedView } from '../../hooks/useEmbeddedView';
+import { useWarnIfOutsideEmbeddedSession } from '../../hooks/useWarnIfOutsideEmbeddedSession';
 import type { IterableEmbeddedComponentProps } from '../../types/IterableEmbeddedComponentProps';
+import { EmbeddedSessionDevWarning } from '../EmbeddedSessionDevWarning/EmbeddedSessionDevWarning';
 import { IMAGE_HEIGHT, styles } from './IterableEmbeddedCard.styles';
 
+const COMPONENT_NAME = 'IterableEmbeddedCard';
+
 /**
  * TODO: Add default action click handler.  See IterableEmbeddedView for functionality.
  */
@@ -25,6 +29,9 @@ export const IterableEmbeddedCard = ({
   onButtonClick = () => {},
   onMessageClick = () => {},
 }: IterableEmbeddedComponentProps) => {
+  const showEmbeddedSessionWarning =
+    useWarnIfOutsideEmbeddedSession(COMPONENT_NAME);
+
   const {
     handleButtonClick,
     handleMessageClick,
@@ -38,6 +45,12 @@ export const IterableEmbeddedCard = ({
   });
   const buttons = message?.elements?.buttons ?? [];
 
+  if (showEmbeddedSessionWarning) {
+    return (
+      <EmbeddedSessionDevWarning visible componentName={COMPONENT_NAME} />
+    );
+  }
+
   return (
     <Pressable onPress={() => handleMessageClick()}>
       <View