@robylon/react-native-sdk 2.2.1-staging.1 → 2.2.3-staging.0

package/src/Chatbotsdk.tsx

@@ -49,9 +49,14 @@ import {
 } from "./utils/webViewStorage";
 import { animateWebViewOpen, animateWebViewClose } from "./utils/animations";
 import { handleDownloadRequest, DownloadRequest } from "./utils/fileDownload";
+import {
+  handleWebViewNavigationRequest,
+  CHATBOT_ORIGIN_WHITELIST,
+} from "./utils/webViewNavigation";
 import {
   SESSION_UPDATED_MESSAGE_TYPE,
   RESUME_SESSION_KEY,
+  SWITCH_SESSION_ACTION,
   extractSessionId,
 } from "./utils/session";
 
@@ -113,6 +118,10 @@ export interface ChatbotRef {
   toggle: () => void;
   isReady: () => boolean;
   getSessionId: () => string | undefined;
+  openToSession: (
+    session_id: string,
+    session_context?: Record<string, any>,
+  ) => void;
 }
 
 interface InternalChatbotProps extends ChatbotProps {
@@ -254,6 +263,29 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
     discreteRef.current = discrete;
     loadingScreenRef.current = loading_screen;
 
+    // openToSession's target, kept apart from the prop mirror above rather
+    // than written into it. That line reassigns on every render, so an
+    // imperative value stored there would be erased by the very state update
+    // that opens the WebView. This one outranks the prop while it is set.
+    const imperativeSessionRef = useRef<string | undefined>(undefined);
+    const resolveResumeTarget = () =>
+      imperativeSessionRef.current ?? resumeSessionRef.current;
+    // Same treatment for the context openToSession was called with. Writing it
+    // into sessionContextRef would be erased on the next render for the same
+    // reason, so a push-initiated switch would report the mounting screen's
+    // context instead of the one describing why the switch happened.
+    const imperativeContextRef = useRef<Record<string, any> | undefined>(
+      undefined,
+    );
+    // A session openToSession was asked to show before the SDK could act on it.
+    const pendingOpenRef = useRef<string | undefined>(undefined);
+    // The init effect runs above where these are declared and must not list
+    // them as dependencies, so it reaches them through refs kept in step below.
+    const openWebViewRef = useRef<(() => void) | undefined>(undefined);
+    const postSessionSwitchRef = useRef<((id: string) => void) | undefined>(
+      undefined,
+    );
+
     // Same reasoning as above: the branding hint is read inside handleMessage,
     // which does not list chatbotConfig among its dependencies.
     const chatbotConfigRef = useRef<ChatbotConfig | null>(null);
@@ -315,6 +347,29 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
         },
         isReady: () => isInitializedRef.current,
         getSessionId: () => sessionIdRef.current,
+        openToSession: (
+          sessionId: string,
+          sessionContext?: Record<string, any>,
+        ) => {
+          if (typeof sessionId !== "string" || sessionId.length === 0) return;
+          // Armed before anything is injected. Opening the WebView for the
+          // first time boots the chat surface, and the registerUserId that
+          // follows has to carry the same target this switch asks for.
+          imperativeSessionRef.current = sessionId;
+          imperativeContextRef.current = sessionContext;
+          // Held rather than dropped when the chat surface has not finished
+          // booting. A notification tapped from a killed app arrives long
+          // before this component is ready, which is the most common way one
+          // is opened at all — returning silently there would land the user in
+          // whatever conversation the app happened to restore. Applied by the
+          // effect that watches isInitialized.
+          if (!isInitializedRef.current) {
+            pendingOpenRef.current = sessionId;
+            return;
+          }
+          openWebView();
+          postSessionSwitch(sessionId);
+        },
       }),
       [isInitialized, isWebViewVisible],
     );
@@ -324,11 +379,24 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
     // throwing client handler cannot break message handling.
     const emitSession = useCallback((data: any) => {
       const sessionId = extractSessionId(data);
-      if (!sessionId || sessionId === sessionIdRef.current) return;
+      if (!sessionId) return;
+      // Captured before the clears below so the context that arrived with
+      // openToSession still reaches the handler for the session it described.
+      const context = imperativeContextRef.current ?? sessionContextRef.current;
+      // The imperative target is an intent about one initialization, matching
+      // the web app's own one-shot handling of it. Once a session id comes
+      // back — whether the backend honoured the target or quietly fell back to
+      // a fresh session — it is spent, so a later reopen cannot revive the
+      // conversation the user has since left. Cleared ahead of the dedupe
+      // below, which returns early when the switch resolved to the session
+      // already on screen.
+      imperativeSessionRef.current = undefined;
+      imperativeContextRef.current = undefined;
+      if (sessionId === sessionIdRef.current) return;
       sessionIdRef.current = sessionId;
 
       try {
-        onSessionRef.current?.(sessionId, sessionContextRef.current ?? {});
+        onSessionRef.current?.(sessionId, context ?? {});
       } catch (error) {
         errorTracker.trackError(
           error instanceof Error
@@ -356,6 +424,29 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
       }
     };
 
+    // Asks the chat surface to abandon whatever conversation it is showing and
+    // re-initialize on this one. Sent alongside the resume target rather than
+    // instead of it: a WebView that has not booted yet reaches the chat surface
+    // through APP_READY -> registerUserId and resumes from there, while one
+    // that is already live needs this message, because by then its resume
+    // target is only read when a session is being created.
+    const postSessionSwitch = useCallback((sessionId: string) => {
+      if (!webViewRef.current) return;
+      const messageData = {
+        name: SWITCH_SESSION_ACTION,
+        action: SWITCH_SESSION_ACTION,
+        data: { [RESUME_SESSION_KEY]: sessionId },
+      };
+      // Not logged, even redacted: there is nothing in this payload but the
+      // session id.
+      webViewRef.current.injectJavaScript(`
+        window.postMessage(${JSON.stringify(messageData)}, '*');
+        true;
+      `);
+    }, []);
+
+    postSessionSwitchRef.current = postSessionSwitch;
+
     const executeStorageOp = useCallback(
       (operation: () => void) => {
         if (isStorageReady) {
@@ -503,7 +594,7 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
                 data: {
                   userId: effectiveUserId,
                   ...initLoadHint,
-                  [RESUME_SESSION_KEY]: resumeSessionRef.current || undefined,
+                  [RESUME_SESSION_KEY]: resolveResumeTarget() || undefined,
                   // Sent only when opted in. false is the default and is
                   // conveyed by the key's absence, so integrations that do not
                   // use it keep sending an unchanged payload.
@@ -527,7 +618,7 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
                   ...messageData,
                   data: {
                     ...messageData.data,
-                    [RESUME_SESSION_KEY]: resumeSessionRef.current
+                    [RESUME_SESSION_KEY]: resolveResumeTarget()
                       ? "[redacted]"
                       : undefined,
                   },
@@ -679,7 +770,7 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
             // does not re-trigger the config fetch. Consistent with session_id
             // being an initialization-time input. JSON.stringify drops the key
             // when there is nothing to resume.
-            resumable_session_id: resumeSessionRef.current || undefined,
+            resumable_session_id: resolveResumeTarget() || undefined,
             // See the registerUserId payload — omitted when false.
             discrete: discreteRef.current ? true : undefined,
             org_id: api_key,
@@ -819,6 +910,8 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
       }
     }, [enableAnimation, animatedValues, externalOnOpen, emitEvent]);
 
+    openWebViewRef.current = openWebView;
+
     // Handle closing the chatbot
     const closeWebView = useCallback(() => {
       if (webViewRef.current) {
@@ -862,6 +955,16 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
         isInitializedRef.current = true;
         setIsInitialized(true);
         onReady?.();
+
+        // Apply a session the client asked for before the SDK could act on it.
+        // After onReady, so a client that also opens the chatbot from there
+        // has already run and this lands on top rather than being overwritten.
+        const pending = pendingOpenRef.current;
+        if (pending) {
+          pendingOpenRef.current = undefined;
+          openWebViewRef.current?.();
+          postSessionSwitchRef.current?.(pending);
+        }
       }
     }, [loading, chatbotConfig, effectiveUserId, isInitialized, onReady]);
 
@@ -1037,14 +1140,19 @@ const Chatbot = forwardRef<ChatbotRef, InternalChatbotProps>(
                       cacheEnabled={true}
                       scrollEnabled={true}
                       bounces={false}
-                      onShouldStartLoadWithRequest={(request) => {
-                        return (
-                          request.url.startsWith(BASE_CHATBOT_URL) ||
-                          request.url.startsWith(
-                            chatbotConfig?.chat_iframe_url || "",
-                          )
-                        );
-                      }}
+                      // The library's default whitelist is http/https, and it
+                      // answers anything outside it itself rather than calling
+                      // the handler below — which is why `tel:` used to die in
+                      // its canOpenURL check. This adds the handoff schemes to
+                      // that default instead of replacing it, so every other
+                      // scheme keeps the library's handling.
+                      originWhitelist={CHATBOT_ORIGIN_WHITELIST}
+                      onShouldStartLoadWithRequest={(request) =>
+                        handleWebViewNavigationRequest(request, [
+                          BASE_CHATBOT_URL,
+                          chatbotConfig?.chat_iframe_url,
+                        ])
+                      }
                       startInLoadingState={isFirstLoadRef.current}
                       onLoadEnd={() => {
                         if (__DEV__) {

package/src/utils/session.ts

@@ -13,6 +13,18 @@ export const SESSION_UPDATED_MESSAGE_TYPE = "SESSION_UPDATED";
 /** Key carrying the resume target inside the `registerUserId` payload. */
 export const RESUME_SESSION_KEY = "sessionId";
 
+/**
+ * Action the web app treats as an authoritative switch to another conversation.
+ *
+ * The resume target on `registerUserId` is only consulted while a session is
+ * being created, so re-sending it to a chat surface that has already booted
+ * arms a value nothing goes on to consume. A notification tap is exactly that
+ * case — the WebView is warm and usually showing a different conversation — so
+ * the switch travels as its own intent, which the web app answers by tearing
+ * down the conversation on screen and re-initializing on the target.
+ */
+export const SWITCH_SESSION_ACTION = "switch_session";
+
 /**
  * Pulls the session id out of a `SESSION_UPDATED` payload.
  *

package/src/utils/webViewNavigation.ts

@@ -0,0 +1,132 @@
+/**
+ * File: src/utils/webViewNavigation.ts
+ * Decides which navigations stay inside the chatbot WebView and hands the rest
+ * to the OS.
+ *
+ * Returning `false` from `onShouldStartLoadWithRequest` only cancels the
+ * navigation: neither platform then falls back to the OS, so without this an
+ * external link (`https://…`) or an app handoff (`tel:`, `mailto:`) silently
+ * does nothing.
+ */
+
+import { Linking } from "react-native";
+import { logger } from "./logger";
+
+/**
+ * Schemes the WebView resolves against its own document. Handing these to
+ * `Linking` would only produce an "unsupported URL" error.
+ */
+const INTERNAL_SCHEMES = ["about:", "javascript:", "data:", "blob:"];
+
+/**
+ * Schemes that hand the URL to another app rather than rendering a document.
+ *
+ * The chat surface requests these from a detached iframe on purpose: the
+ * WebView cannot render them, so navigating the page itself would leave the
+ * user looking at an ERR_UNKNOWN_URL_SCHEME error instead of the conversation.
+ * That makes them the one kind of sub-frame navigation worth acting on.
+ */
+const APP_HANDOFF_SCHEMES = [
+  "tel:",
+  "sms:",
+  "mailto:",
+  "facetime:",
+  "whatsapp:",
+  "geo:",
+  "maps:",
+  "intent:",
+];
+
+/**
+ * What to pass as the WebView's `originWhitelist`.
+ *
+ * The library's default is http/https only, and it answers anything outside
+ * that itself — with a `canOpenURL` check that Android 11 makes fail for an
+ * installed dialer. So the handoff schemes are added to the default rather
+ * than the default being replaced: every other scheme keeps the library's
+ * handling, and this list cannot drift from the one above.
+ */
+export const CHATBOT_ORIGIN_WHITELIST: string[] = [
+  "http://*",
+  "https://*",
+  ...APP_HANDOFF_SCHEMES.map((scheme) => `${scheme}*`),
+];
+
+const isAppHandoffScheme = (url?: string): boolean => {
+  const lowerUrl = trimUrl(url)?.toLowerCase();
+  return !!APP_HANDOFF_SCHEMES?.some((scheme) => lowerUrl?.startsWith(scheme));
+};
+
+/** `hasTargetFrame` is sent by iOS but missing from the library's TS types. */
+export interface WebViewNavigationRequestLike {
+  url?: string;
+  isTopFrame?: boolean;
+  hasTargetFrame?: boolean;
+}
+
+const trimUrl = (url?: string): string => url?.trim() || "";
+
+const isInternalScheme = (url?: string): boolean => {
+  const lowerUrl = trimUrl(url)?.toLowerCase();
+  return !!INTERNAL_SCHEMES?.some((scheme) => lowerUrl?.startsWith(scheme));
+};
+
+const matchesAnyPrefix = (
+  url: string,
+  prefixes?: (string | undefined)[],
+): boolean =>
+  !!prefixes?.some((prefix) => !!prefix?.trim() && url?.startsWith(prefix));
+
+export const shouldLoadInChatbotWebView = (
+  request?: WebViewNavigationRequestLike,
+  chatbotUrlPrefixes?: (string | undefined)[],
+): boolean => matchesAnyPrefix(trimUrl(request?.url), chatbotUrlPrefixes);
+
+/**
+ * A sub-frame load is a resource the page pulled in — an embedded player, a
+ * tracking pixel — not a destination the user asked for, so it must not launch
+ * an app. A popup (`window.open`, `target="_blank"`) reports no target frame
+ * and is a real destination.
+ *
+ * Both flags are iOS-only; Android only reports frame-level navigations here.
+ */
+const isUserDestination = (request?: WebViewNavigationRequestLike): boolean =>
+  request?.isTopFrame !== false ||
+  request?.hasTargetFrame === false ||
+  // The chat surface asks for these from a hidden frame deliberately, so the
+  // sub-frame rule above would reject exactly the case it was written for. A
+  // pixel or embedded player is http(s) and is still rejected.
+  isAppHandoffScheme(request?.url);
+
+const canLeaveWebView = (request?: WebViewNavigationRequestLike): boolean =>
+  !!trimUrl(request?.url) &&
+  !isInternalScheme(request?.url) &&
+  isUserDestination(request);
+
+export const openUrlOutsideWebView = async (url?: string): Promise<boolean> => {
+  try {
+    await Linking.openURL(trimUrl(url));
+    return true;
+  } catch (error) {
+    logger.warn("Failed to open URL outside the WebView", {
+      url,
+      error: error instanceof Error ? error?.message : String(error),
+    });
+    return false;
+  }
+};
+
+/**
+ * Synchronous by contract: `onShouldStartLoadWithRequest` needs its answer
+ * immediately, so the external launch is fired off without being awaited.
+ */
+export const handleWebViewNavigationRequest = (
+  request?: WebViewNavigationRequestLike,
+  chatbotUrlPrefixes?: (string | undefined)[],
+): boolean => {
+  if (shouldLoadInChatbotWebView(request, chatbotUrlPrefixes)) return true;
+  if (!canLeaveWebView(request)) return false;
+  logger.debug("Opening navigation outside the WebView", { url: request?.url });
+  void openUrlOutsideWebView(request?.url);
+  return false;
+};

package/src/versions/version.staging.ts

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not modify it manually.
-export const SDK_VERSION = '2.2.1-staging.1';
+export const SDK_VERSION = '2.2.3-staging.0';