@glomopay/react-native-sdk 1.3.4 → 2.0.1

package/src/use-lrs-checkout.tsx

@@ -5,9 +5,9 @@ import { Platform, type NativeSyntheticEvent } from "react-native";
 
 import { WebViewNavigation, WebViewMessageEvent, type WebView } from "react-native-webview";
 
-import { InjectionScripts } from "./injections";
+import { InjectionScripts } from "./injections/index";
 import { initializeSegment } from "./config/segment";
-import { DEFAULT_BASE_CHECKOUT_URL } from "./config/base";
+import { resolveServerConfig, type GlomoLrsServer } from "./config/base";
 import { isValidPublicKey, isValidOrderId, isValidUrl, isValidPaymentPayload, safeCallback } from "./utils/validation";
 import { checkDeviceCompliance, isComplianceCheckAvailable } from "./utils/device-compliance";
 import {
@@ -20,6 +20,7 @@ import {
     trackPaymentFailure,
     trackPaymentTerminate,
     trackConnectionError,
+    trackEducationStepsShown,
     trackSdkError,
     trackInvalidMessageReceived,
     type SdkError,
@@ -42,6 +43,13 @@ export type LrsCheckoutStatus =
     // LRS checkout flow aborted midway. User can retry the flow on the same orderId
     | "payment_cancelled";
 
+/**
+ * Tracks whether the education carousel WebView has signalled that it has content to show.
+ * - "pending": waiting for the carousel to report its state (default/reset value)
+ * - "hasContent": carousel sent lrs.has_education_steps and should be shown to the user
+ */
+export type EducationCarouselState = "pending" | "hasContent";
+
 /** The payload for a successful or failed payment */
 export interface GlomoLrsCheckoutPayload {
     orderId: string;
@@ -51,7 +59,7 @@ export interface GlomoLrsCheckoutPayload {
 
 /** The options for the useLrsCheckout hook */
 export interface UseLrsCheckoutOptions {
-    server?: string;
+    server?: GlomoLrsServer;
     publicKey: string;
     orderId: string;
     onPaymentSuccess: (payload: GlomoLrsCheckoutPayload) => void;
@@ -69,19 +77,25 @@ export interface UseLrsCheckoutReturn {
     showCheckout: boolean;
     flowWebViewUrl: string;
     showFlowWebView: boolean;
+    educationCarouselUrl: string;
+    educationCarouselState: EducationCarouselState;
     checkoutUrl: string;
     mainWebViewRef: React.RefObject<WebView>;
     flowWebViewRef: React.RefObject<WebView>;
+    educationCarouselWebViewRef: React.RefObject<WebView>;
     handleMainWebViewMessage: (event: WebViewMessageEvent) => void;
     handleFlowWebViewMessage: (event: WebViewMessageEvent) => void;
+    handleEducationCarouselWebViewMessage: (event: WebViewMessageEvent) => void;
     handleError: (
         syntheticEvent: NativeSyntheticEvent<{ code?: number; domain?: string; description?: string }>
     ) => void;
     handleHttpError: (syntheticEvent: NativeSyntheticEvent<{ statusCode: number; description?: string }>) => void;
     handleNavigationStateChange: (navState: WebViewNavigation) => void;
     handleModalBackButton: () => void;
+    handleFlowBack: () => void;
     injectedMain?: string;
     injectedFlow?: string;
+    injectedEducationCarousel?: string;
 }
 
 /** The main SDK hook for the GlomoPay LRS Checkout flow */
@@ -102,9 +116,11 @@ export function useLrsCheckout(
     // Refs for the WebViews
     const mainWebViewRef = useRef<WebView>(null);
     const flowWebViewRef = useRef<WebView>(null);
+    const educationCarouselWebViewRef = useRef<WebView>(null);
 
-    // Using the server prop if provided, otherwise using the default production URL
-    const baseCheckoutUrl = useMemo(() => server ?? DEFAULT_BASE_CHECKOUT_URL, [server]);
+    // Resolving checkout and carousel URLs from the selected SDK server
+    const serverConfig = useMemo(() => resolveServerConfig(server), [server]);
+    const baseCheckoutUrl = serverConfig.checkoutBaseUrl;
 
     /**
      * The main checkout URL for the LRS flow
@@ -168,6 +184,58 @@ export function useLrsCheckout(
         }
     }, [baseCheckoutUrl, orderId, publicKey, mockMode, devMode, onSdkError]);
 
+    /**
+     * The education carousel URL, built from the server config with the current orderId and publicKey.
+     * Loaded in a hidden WebView alongside the flow WebView; shown only once the carousel signals it has content.
+     */
+    const educationCarouselUrl = useMemo(() => {
+        try {
+            const baseEducationCarouselUrl = serverConfig.educationCarouselBaseUrl;
+            const separator = baseEducationCarouselUrl.includes("?") ? "&" : "?";
+            const finalUrl =
+                `${baseEducationCarouselUrl}${separator}orderId=${encodeURIComponent(orderId)}` +
+                `&publicKey=${encodeURIComponent(publicKey)}`;
+
+            if (!isValidUrl(finalUrl)) {
+                if (devMode) {
+                    console.error("[GlomoPay RN SDK] Generated invalid education carousel URL:", finalUrl);
+                }
+                const errors: SdkError[] = [
+                    {
+                        type: "validation_error",
+                        message: "Generated invalid education carousel URL",
+                    },
+                ];
+                trackSdkError(
+                    errors,
+                    orderId,
+                    publicKey,
+                    devMode,
+                    mockMode,
+                    finalUrl ? finalUrl : finalUrl === null ? "null" : "undefined"
+                );
+                return "";
+            }
+
+            if (devMode) {
+                console.log("[GlomoPay RN SDK] Education Carousel URL:", finalUrl);
+            }
+            return finalUrl;
+        } catch (error) {
+            if (devMode) {
+                console.error("[GlomoPay RN SDK] Error building education carousel URL:", error);
+            }
+            const errors: SdkError[] = [
+                {
+                    type: "validation_error",
+                    message: `Error building education carousel URL: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ];
+            trackSdkError(errors, orderId, publicKey, devMode, mockMode, "");
+            return "";
+        }
+    }, [serverConfig, orderId, publicKey, devMode, mockMode]);
+
     // Checkout status state
     const [status, setStatus] = useState<LrsCheckoutStatus>("ready");
 
@@ -176,6 +244,15 @@ export function useLrsCheckout(
 
     const [showFlowWebView, setShowFlowWebView] = useState(false);
     const [flowWebViewUrl, setFlowWebViewUrl] = useState<string>("");
+    const [educationCarouselState, setEducationCarouselState] = useState<EducationCarouselState>("pending");
+
+    useEffect(() => {
+        if (devMode) {
+            console.log(
+                `[GlomoPay RN SDK] Carousel state snapshot: status=${status}, showCheckout=${showCheckout}, showFlowWebView=${showFlowWebView}, flowWebViewUrl=${flowWebViewUrl || "<empty>"}, educationCarouselState=${educationCarouselState}, educationCarouselUrl=${educationCarouselUrl || "<empty>"}`
+            );
+        }
+    }, [devMode, status, showCheckout, showFlowWebView, flowWebViewUrl, educationCarouselState, educationCarouselUrl]);
 
     // Handler for the WebView errors
     const handleError = useCallback(
@@ -213,6 +290,7 @@ export function useLrsCheckout(
                     setShowCheckout(false);
                     setShowFlowWebView(false);
                     setFlowWebViewUrl("");
+                    setEducationCarouselState("pending");
 
                     // Calling onConnectionError callback if provided
                     safeCallback(onConnectionError, [nativeEvent], "onConnectionError", devMode);
@@ -229,7 +307,7 @@ export function useLrsCheckout(
                 }
             }
         },
-        [devMode, onConnectionError, checkoutUrl]
+        [devMode, onConnectionError, checkoutUrl, orderId, publicKey, mockMode]
     );
 
     // Handler for the WebView HTTP errors
@@ -293,6 +371,7 @@ export function useLrsCheckout(
                         }
                         setFlowWebViewUrl(url);
                         setShowFlowWebView(true);
+                        setEducationCarouselState("pending");
                         // Tracking window.open interception
                         trackWindowOpen("main", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
                     } else {
@@ -313,6 +392,7 @@ export function useLrsCheckout(
                     }
                     setShowFlowWebView(false);
                     setFlowWebViewUrl("");
+                    setEducationCarouselState("pending");
                     // Tracking window.close interception
                     trackWindowClose("main", orderId, publicKey, devMode, mockMode, checkoutUrl);
                     return;
@@ -334,6 +414,7 @@ export function useLrsCheckout(
                             setShowCheckout(false);
                             setShowFlowWebView(false);
                             setFlowWebViewUrl("");
+                            setEducationCarouselState("pending");
                             setStatus("payment_successful");
                             safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
                             // Tracking payment success callback
@@ -364,6 +445,7 @@ export function useLrsCheckout(
                             setShowCheckout(false);
                             setShowFlowWebView(false);
                             setFlowWebViewUrl("");
+                            setEducationCarouselState("pending");
                             setStatus("payment_failed");
                             safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
                             // Tracking payment failure callback
@@ -391,6 +473,7 @@ export function useLrsCheckout(
                         setShowCheckout(false);
                         setShowFlowWebView(false);
                         setFlowWebViewUrl("");
+                        setEducationCarouselState("pending");
                         safeCallback(onPaymentTerminate, [], "onPaymentTerminate", devMode);
                         // Tracking payment terminate callback
                         trackPaymentTerminate(orderId, "checkout_closed", publicKey, devMode, mockMode, checkoutUrl);
@@ -448,6 +531,7 @@ export function useLrsCheckout(
                             console.log(`[GlomoPay RN SDK] window.open called from FlowWebView: ${url}`);
                         }
                         setFlowWebViewUrl(url);
+                        setEducationCarouselState("pending");
                         // Tracking window.open interception
                         trackWindowOpen("flow", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
                     } else {
@@ -468,6 +552,7 @@ export function useLrsCheckout(
                     }
                     setShowFlowWebView(false);
                     setFlowWebViewUrl("");
+                    setEducationCarouselState("pending");
                     // Tracking window.close interception
                     trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
                     return;
@@ -488,6 +573,7 @@ export function useLrsCheckout(
                             setShowFlowWebView(false);
                             setShowCheckout(false);
                             setFlowWebViewUrl("");
+                            setEducationCarouselState("pending");
                             setStatus("payment_successful");
                             safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
                             // Tracking payment success callback
@@ -521,6 +607,7 @@ export function useLrsCheckout(
                             setShowFlowWebView(false);
                             setShowCheckout(false);
                             setFlowWebViewUrl("");
+                            setEducationCarouselState("pending");
                             setStatus("payment_failed");
                             safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
                             // Tracking payment failure callback
@@ -552,6 +639,52 @@ export function useLrsCheckout(
         [onPaymentSuccess, onPaymentFailure, devMode, mockMode, orderId, publicKey, flowWebViewUrl, checkoutUrl]
     );
 
+    // Handler for the education carousel WebView messages
+    const handleEducationCarouselWebViewMessage = useCallback(
+        (event: WebViewMessageEvent) => {
+            try {
+                const data = event.nativeEvent?.data;
+                if (!data || typeof data !== "string") {
+                    if (devMode) {
+                        console.warn("[GlomoPay RN SDK] Invalid message data from EducationCarouselWebView");
+                    }
+                    return;
+                }
+
+                const message = JSON.parse(data);
+                if (devMode) {
+                    console.log("[GlomoPay RN SDK] EducationCarouselWebView Message received:", message.type, message);
+                }
+
+                if (message.type === "console") {
+                    if (devMode) {
+                        console.log(`[GlomoPay RN SDK] [EducationCarousel] ${message.message}`);
+                    }
+                    return;
+                }
+
+                if (message.type === "lrs.has_education_steps") {
+                    const nextState: EducationCarouselState = "hasContent";
+
+                    if (devMode) {
+                        console.log(
+                            `[GlomoPay RN SDK] Education carousel signal received: value=${String(message.value)} source=${message.source || "unknown"} payload=${JSON.stringify(message.payload || {})}`
+                        );
+                    }
+
+                    trackEducationStepsShown(orderId, publicKey, devMode, mockMode, checkoutUrl, message.source);
+                    setEducationCarouselState(nextState);
+                    return;
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[GlomoPay RN SDK] Error parsing EducationCarouselWebView message:", error);
+                }
+            }
+        },
+        [checkoutUrl, devMode, mockMode, orderId, publicKey]
+    );
+
     // Handler for the navigation state changes
     const handleNavigationStateChange = useCallback(
         (navState: WebViewNavigation) => {
@@ -571,6 +704,7 @@ export function useLrsCheckout(
             if (showFlowWebView) {
                 setShowFlowWebView(false);
                 setFlowWebViewUrl("");
+                setEducationCarouselState("pending");
             }
             setShowCheckout(false);
             if (status === "payment_in_progress") {
@@ -592,7 +726,18 @@ export function useLrsCheckout(
                 console.error("[GlomoPay RN SDK] Error in handleModalBackButton:", error);
             }
         }
-    }, [showFlowWebView, devMode, onPaymentTerminate, status, orderId, mockMode, checkoutUrl]);
+    }, [showFlowWebView, devMode, onPaymentTerminate, status, orderId, publicKey, mockMode, checkoutUrl]);
+
+    /** Closes the flow WebView and returns to the main checkout */
+    const handleFlowBack = useCallback(() => {
+        if (devMode) {
+            console.log("[GlomoPay RN SDK] Flow WebView back button pressed");
+        }
+        setShowFlowWebView(false);
+        setFlowWebViewUrl("");
+        setEducationCarouselState("pending");
+        trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+    }, [devMode, orderId, publicKey, mockMode, checkoutUrl]);
 
     /**
      * Initiator method for the LRS Checkout flow.
@@ -779,6 +924,7 @@ export function useLrsCheckout(
 
         setShowFlowWebView(false);
         setFlowWebViewUrl("");
+        setEducationCarouselState("pending");
         setStatus("payment_in_progress");
 
         // Tracking successful start
@@ -796,7 +942,7 @@ export function useLrsCheckout(
     // Resetting checkout flow if orderId or publicKey are changed
     useEffect(() => {
         if (orderId && publicKey) {
-            // Only resetting the checkout flow if the current status is that ofa terminal state
+            // Only resetting the checkout flow if the current status is that of a terminal state
             if (status === "payment_successful" || status === "payment_failed" || status === "payment_cancelled") {
                 if (devMode) {
                     console.log(
@@ -816,6 +962,7 @@ export function useLrsCheckout(
             setShowCheckout(false);
             setShowFlowWebView(false);
             setFlowWebViewUrl("");
+            setEducationCarouselState("pending");
         };
     }, []);
 
@@ -825,16 +972,22 @@ export function useLrsCheckout(
         showCheckout,
         flowWebViewUrl,
         showFlowWebView,
+        educationCarouselUrl,
+        educationCarouselState,
         checkoutUrl,
         mainWebViewRef,
         flowWebViewRef,
+        educationCarouselWebViewRef,
         handleMainWebViewMessage,
         handleFlowWebViewMessage,
+        handleEducationCarouselWebViewMessage,
         handleError,
         handleHttpError,
         handleNavigationStateChange,
         handleModalBackButton,
+        handleFlowBack,
         injectedMain: InjectionScripts.main,
         injectedFlow: InjectionScripts.flow,
+        injectedEducationCarousel: InjectionScripts.educationCarousel,
     };
 }

package/src/utils/analytics.ts

@@ -502,6 +502,35 @@ export function trackConnectionError(
     });
 }
 
+/**
+ * Tracks when the education carousel reports that it has visible education steps
+ *
+ * @param orderId - The order ID
+ * @param publicKey - The public key of the merchant
+ * @param devMode - Whether dev mode is enabled
+ * @param mockMode - Whether mock mode is enabled
+ * @param lrsUrl - The LRS checkout URL
+ * @param source - Where the carousel event originated
+ */
+export function trackEducationStepsShown(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    lrsUrl?: string,
+    source?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
+        ...(source && { source }),
+    };
+    trackEvent("LRS Has Education Steps", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error(`[GlomoPay RN SDK] Event tracking error on education steps shown event:`, error);
+        }
+    });
+}
+
 /**
  * Tracks when onSdkError callback is invoked
  *