[SDK-387] automatically start and end sessions

example/src/components/Embedded/Embedded.tsx

@@ -1,3 +1,5 @@
+import { useIsFocused } from '@react-navigation/native';
+import { useCallback, useState } from 'react';
 import {
   Alert,
   Modal,
@@ -7,22 +9,24 @@ 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';
 
 const DEFAULT_CONFIG_JSON = `{
 }`;
 
 export const Embedded = () => {
+  const isFocused = useIsFocused();
   const [placementIdsInput, setPlacementIdsInput] = useState<string>('');
   const [embeddedMessages, setEmbeddedMessages] = useState<
     IterableEmbeddedMessage[]
@@ -44,18 +48,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 +89,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 +153,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>
@@ -230,14 +210,16 @@ export const Embedded = () => {
       <View style={styles.hr} />
       <ScrollView>
         <View style={styles.embeddedSection}>
-          {embeddedMessages.map((message) => (
-            <IterableEmbeddedView
-              key={message.metadata.messageId}
-              viewType={selectedViewType}
-              message={message}
-              config={viewConfig}
-            />
-          ))}
+          <EmbeddedSessionManager isActive={isFocused}>
+            {embeddedMessages.map((message) => (
+              <IterableEmbeddedView
+                key={message.metadata.messageId}
+                viewType={selectedViewType}
+                message={message}
+                config={viewConfig}
+              />
+            ))}
+          </EmbeddedSessionManager>
         </View>
       </ScrollView>
     </SafeAreaView>

src/core/classes/Iterable.ts

@@ -1108,6 +1108,8 @@ export class Iterable {
           }
         );
       }
+
+      Iterable.embeddedManager.syncMessages();
     }
   }
 

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,34 @@
+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;
+}
+
+/**
+ * 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 component 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/EmbeddedSessionDevWarning/index.ts

@@ -0,0 +1,2 @@
+export * from './EmbeddedSessionDevWarning';
+export { EmbeddedSessionDevWarning as default } from './EmbeddedSessionDevWarning';

src/embedded/components/EmbeddedSessionManager.test.tsx

@@ -0,0 +1,98 @@
+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);
+  });
+
+  it('does not start session when isActive is false', () => {
+    const { unmount } = render(
+      <EmbeddedSessionManager isActive={false}>
+        <Text>child</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.startSession).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(Iterable.embeddedManager.endSession).not.toHaveBeenCalled();
+  });
+
+  it('ends session when isActive becomes false and restarts when true again', () => {
+    const { rerender } = render(
+      <EmbeddedSessionManager isActive={true}>
+        <Text>child</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.startSession).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <EmbeddedSessionManager isActive={false}>
+        <Text>child</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.endSession).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <EmbeddedSessionManager isActive={true}>
+        <Text>child</Text>
+      </EmbeddedSessionManager>
+    );
+
+    expect(Iterable.embeddedManager.startSession).toHaveBeenCalledTimes(2);
+  });
+});

src/embedded/components/EmbeddedSessionManager.tsx

@@ -0,0 +1,49 @@
+import type { PropsWithChildren, ReactNode } from 'react';
+import { useContext, useEffect } from 'react';
+
+import { Iterable } from '../../core/classes/Iterable';
+import { EmbeddedSessionContext } from '../context/EmbeddedSessionContext';
+
+export interface EmbeddedSessionManagerProps {
+  children?: ReactNode;
+  /**
+   * When `false`, this wrapper does not start an embedded session (e.g. host
+   * screen not focused). Defaults to `true`.
+   *
+   * This is not necessary to use.  It is only useful if you want to avoid
+   * starting the session when the screen is hidden but still technically there.
+   */
+  isActive?: boolean;
+}
+
+/**
+ * Wraps embedded content and tracks an embedded session for its lifecycle.
+ *
+ * If nested, only the top-most wrapper starts and ends the session.
+ *
+ * There should only be one EmbeddedSessionManager per screen.
+ */
+export const EmbeddedSessionManager = ({
+  children,
+  isActive = true,
+}: PropsWithChildren<EmbeddedSessionManagerProps>) => {
+  const hasActiveParentSession = useContext(EmbeddedSessionContext);
+
+  useEffect(() => {
+    if (hasActiveParentSession || !isActive) {
+      return;
+    }
+
+    Iterable.embeddedManager.startSession();
+
+    return () => {
+      Iterable.embeddedManager.endSession();
+    };
+  }, [hasActiveParentSession, isActive]);
+
+  return (
+    <EmbeddedSessionContext.Provider value={true}>
+      {children}
+    </EmbeddedSessionContext.Provider>
+  );
+};