@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/index.ts

@@ -29,7 +29,6 @@ import {
   type CustomScrollIntoView,
   type ScrollPadding,
 } from './anchors/scrollConfig';
-import { setSurfaceInteractionBlocking as setSurfaceInteractionBlockingConfig } from './surfaces/surfaceInteractionConfig';
 import { clearAnonymousId, getOrCreateAnonymousId } from './anonymousId';
 import {
   didHandleURL,
@@ -44,6 +43,8 @@ import {
   mergeDeviceContextUserAttributes,
   type DeviceContext,
 } from './deviceContext';
+import { setEvalJsBridgeHandlers } from './evalJs/evalJsBridge';
+import { evalJsController } from './evalJs/evalJsController';
 import {
   cacheHostAppVersionAtInit,
   getCachedHostAppVersion,
@@ -52,20 +53,34 @@ import {
   type HostAppVersion,
 } from './hostAppVersion';
 import { LifecycleController } from './lifecycle';
-import { setHostOnNavigate, type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
+import {
+  openFlowNavigateUrl,
+  setHostOnNavigate,
+  type FlowNavigateHandler,
+} from './navigation/openFlowNavigateUrl';
 import { NetworkController } from './network';
 import { getPairingController, installPairingController } from './pairing/pairingRuntime';
+import {
+  attachBannerSessionEngine,
+  clearBannerSessionEngineLocalSession,
+  getBannerSessionEngine,
+  resetBannerSessionEngine,
+} from './runtime/bannerEngine';
 import {
   attachClientConditionEngine,
   resetClientConditionEngine,
 } from './runtime/clientConditions';
 import {
   attachFlowSessionEngine,
+  cancelPendingDraftEnd,
   clearFlowSessionEngineLocalSession,
+  endDraftFlowSession,
+  endEvalJsFlowSession,
   getFlowSessionEngine,
   hasActiveFlowSession,
   resetFlowSessionEngine,
 } from './runtime/flowEngine';
+import { isolateAsync, isolateSync } from './runtime/isolateCall';
 import { getUserflowCore } from './runtime/userflowCore';
 import {
   disableScreenTracking,
@@ -77,10 +92,13 @@ import {
   screenViewedAttributes,
   setScreenChangeReporter,
 } from './screenTracker';
+import { setSurfaceInteractionBlocking as setSurfaceInteractionBlockingConfig } from './surfaces/surfaceInteractionConfig';
 
 export { SDK_VERSION } from './version';
 export type { DeviceContext, DeviceOs, DeviceType, SdkPlatform } from './deviceContext';
 export type { HostAppVersion, HostAppVersionSource } from './hostAppVersion';
+export { EmbedBannerPlaceholder } from './runtime/EmbedBannerPlaceholder';
+export type { EmbedBannerPlaceholderProps } from './runtime/EmbedBannerPlaceholder';
 export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
 export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
 export { useFlowSessionState } from './runtime/useFlowSessionState';
@@ -156,11 +174,14 @@ const lifecycle = new LifecycleController({
     core.resume();
     // After reconnect, flush mid-flow client messages that failed while offline.
     void getFlowSessionEngine(core).flushPendingSends();
+    void getBannerSessionEngine(core).flushPendingSends();
   },
   clearLocalSession: () => {
     clearFlowSessionEngineLocalSession();
+    clearBannerSessionEngineLocalSession();
     // Engine may not exist yet; still clear any transport join resume id.
     core.setFlowSessionId(null);
+    core.setBannerSessionId(null);
   },
   ensureAlive: () => core.ensureAlive(),
   hasActiveSession: () => hasActiveFlowSession(),
@@ -185,49 +206,43 @@ function armScreenViewedForNextIdentify(): void {
 
 function wireScreenChangeReporter(): void {
   setScreenChangeReporter((location) => {
-    lifecycle.reportActivity();
-    const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
-    notifyAnchorScreenChange(screenKey);
-    anchorChangeTicker.notify();
-    const identified = core.getUserId() != null;
-    if (__DEV__) {
-      // eslint-disable-next-line no-console -- intentional development diagnostic
-      console.log(
-        '[Userflow] updateScreen',
-        location,
-        identified ? '(push UpdateClientContext)' : '(buffered until identify)',
-      );
-    }
-    // Mirrors web: only pushes UpdateClientContext after identify; before that the
-    // location is remembered and included on the next end-user channel join.
-    void core.updateScreen(location).catch((error: unknown) => {
-      // Screen updates are best-effort; connection drops / rate limits should not
-      // surface to the host app's navigation path.
+    isolateSync('updateScreen', () => {
+      lifecycle.reportActivity();
+      const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
+      notifyAnchorScreenChange(screenKey);
+      anchorChangeTicker.notify();
+      const identified = core.getUserId() != null;
       if (__DEV__) {
         // eslint-disable-next-line no-console -- intentional development diagnostic
-        console.warn('[Userflow] updateScreen failed', error);
+        console.log(
+          '[Userflow] updateScreen',
+          location,
+          identified ? '(push UpdateClientContext)' : '(buffered until identify)',
+        );
       }
-    });
+      // Mirrors web: only pushes UpdateClientContext after identify; before that the
+      // location is remembered and included on the next end-user channel join.
+      void isolateAsync('updateScreen', () => core.updateScreen(location), {
+        rethrowHostContract: false,
+      });
 
-    const attrs = screenViewedAttributes(location);
-    if (!attrs) return;
-    if (!identified) {
-      screenViewedAwaitingIdentify = true;
-      return;
-    }
-    screenViewedAwaitingIdentify = false;
-    if (__DEV__) {
-      // eslint-disable-next-line no-console -- intentional development diagnostic
-      console.log('[Userflow] track', SCREEN_VIEWED_EVENT, attrs);
-    }
-    void core.track(SCREEN_VIEWED_EVENT, attrs).catch((error: unknown) => {
-      // Screen views are best-effort; connection drops / rate limits should not
-      // surface to the host app's navigation path. Each accepted screen sends
-      // UpdateClientContext + TrackEvent (two slots of the 100/min cap).
+      const attrs = screenViewedAttributes(location);
+      if (!attrs) return;
+      if (!identified) {
+        screenViewedAwaitingIdentify = true;
+        return;
+      }
+      screenViewedAwaitingIdentify = false;
       if (__DEV__) {
         // eslint-disable-next-line no-console -- intentional development diagnostic
-        console.warn('[Userflow] track', SCREEN_VIEWED_EVENT, 'failed', error);
+        console.log('[Userflow] track', SCREEN_VIEWED_EVENT, attrs);
       }
+      // Screen views are best-effort; connection drops / rate limits should not
+      // surface to the host app's navigation path. Each accepted screen sends
+      // UpdateClientContext + TrackEvent (two slots of the 100/min cap).
+      void isolateAsync('track', () => core.track(SCREEN_VIEWED_EVENT, attrs), {
+        rethrowHostContract: false,
+      });
     });
   });
 }
@@ -249,6 +264,7 @@ function mergeSystemUserAttributes<T extends Record<string, unknown>>(
 
 async function afterIdentify(): Promise<void> {
   attachFlowSessionEngine(core);
+  attachBannerSessionEngine(core);
   attachClientConditionEngine(core);
   getPairingController(core).notifyIdentified();
   lifecycle.reportActivity();
@@ -290,15 +306,23 @@ export const Userflow = {
       clearLocalSession: () => {
         clearFlowSessionEngineLocalSession();
         core.setFlowSessionId(null);
+        clearBannerSessionEngineLocalSession();
+        core.setBannerSessionId(null);
+        evalJsController.reset();
       },
+      endDraftSession: endDraftFlowSession,
+      cancelPendingDraftEnd,
     });
     pairing.notifyInitStarted();
     void pairing.start();
 
     return core.init(config).then(
-      async (resolved) => {
+      (resolved) => {
         enableScreenTracking();
-        await pairing.notifyInitialized();
+        // Pairing connect can take the full socket timeout. Identify, and the
+        // end-user socket that delivers the preview, must not wait on it.
+        // notifyInitialized never rejects; the relay queue covers either order.
+        void pairing.notifyInitialized();
         return resolved;
       },
       (error: unknown) => {
@@ -338,6 +362,9 @@ export const Userflow = {
     if (previousId != null && previousId !== userId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
+      clearBannerSessionEngineLocalSession();
+      core.setBannerSessionId(null);
+      evalJsController.reset();
       await clearAnonymousId();
       armScreenViewedForNextIdentify();
     }
@@ -354,6 +381,9 @@ export const Userflow = {
     if (previousId != null && previousId !== anonymousId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
+      clearBannerSessionEngineLocalSession();
+      core.setBannerSessionId(null);
+      evalJsController.reset();
       armScreenViewedForNextIdentify();
     }
     await core.identify(anonymousId, mergeSystemUserAttributes(attributes), options);
@@ -394,14 +424,21 @@ export const Userflow = {
     lifecycle.reportActivity();
     return core.updateGroup(attributes, options);
   },
-  /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
+  /**
+   * Record a custom analytics event for the current user (and group, unless `userOnly`).
+   * Operational failures (network, rate limit, unexpected SDK bugs) are isolated and
+   * logged; the promise still resolves. `UserflowAuthError` for missing
+   * `init` / `identify` or an invalid event name still rejects.
+   */
   track(
     name: string,
     attributes?: UserflowEventAttributes,
     options?: UserflowTrackOptions,
   ): Promise<void> {
-    lifecycle.reportActivity();
-    return core.track(name, attributes, options);
+    return isolateAsync('track', async () => {
+      lifecycle.reportActivity();
+      await core.track(name, attributes, options);
+    }).then(() => undefined);
   },
   /** The currently identified user id, or `null` before identify. */
   getUserId(): string | null {
@@ -429,10 +466,16 @@ export const Userflow = {
   getFlowSessionEngine() {
     return getFlowSessionEngine(core);
   },
+  /** The banner session engine (created lazily; attach runs after identify). */
+  getBannerSessionEngine() {
+    return getBannerSessionEngine(core);
+  },
   /** Clears the current user identity and disconnects from Userflow. */
   async reset(): Promise<void> {
     resetClientConditionEngine();
     resetFlowSessionEngine();
+    resetBannerSessionEngine();
+    evalJsController.reset();
     core.reset();
     armScreenViewedForNextIdentify();
     await clearAnonymousId();
@@ -442,6 +485,7 @@ export const Userflow = {
     getPairingController(core).stop();
     lifecycle.stop();
     network.stop();
+    evalJsController.reset();
     disableScreenTracking();
     screenViewedAwaitingIdentify = false;
     stopDeepLinking();
@@ -453,7 +497,9 @@ export const Userflow = {
    * host-app activity the SDK does not observe.
    */
   reportActivity(): void {
-    lifecycle.reportActivity();
+    isolateSync('reportActivity', () => {
+      lifecycle.reportActivity();
+    });
   },
   /**
    * Report the active React Navigation (or manual) screen name. Prefer
@@ -462,7 +508,9 @@ export const Userflow = {
    * with `screen` set (Expo Router pathnames use `path` via the Expo helper).
    */
   updateScreen(screenName: string | undefined): void {
-    handleScreenChange(screenName ? { screen: screenName } : undefined);
+    isolateSync('updateScreen', () => {
+      handleScreenChange(screenName ? { screen: screenName } : undefined);
+    });
   },
   /**
    * Sticky header/footer insets applied when scrolling tooltip targets into
@@ -487,6 +535,14 @@ export const Userflow = {
   setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void {
     setSurfaceInteractionBlockingConfig(enabled);
   },
+  /**
+   * Values exposed to Evaluate JavaScript as `window.userflowContext.host`
+   * (language, theme, tab bar height, and anything else the page used to read
+   * from the DOM). Replaces the previous host bag.
+   */
+  setEvalJsContext(values: Record<string, unknown> | null | undefined): void {
+    evalJsController.setHostContext(values ?? {});
+  },
   /**
    * Log the host app's native marketing version (store version), not
    * {@link SDK_VERSION}, and the platform OS (`ios` / `android` / …).
@@ -504,3 +560,31 @@ export const Userflow = {
     logDeviceContextToConsole();
   },
 };
+
+setEvalJsBridgeHandlers({
+  track: (name, attributes) => {
+    void Userflow.track(name, attributes as UserflowAttributes | undefined);
+  },
+  updateUser: (attributes) => {
+    void Userflow.updateUser(attributes as PublicAttributes);
+  },
+  updateGroup: (attributes, options) => {
+    void Userflow.updateGroup(
+      attributes as PublicAttributes,
+      options?.membership ? { membership: options.membership as PublicAttributes } : undefined,
+    );
+  },
+  openUrl: (url) => {
+    void isolateAsync('eval-js-open-url', () => openFlowNavigateUrl(url), {
+      rethrowHostContract: false,
+    });
+  },
+  endFlow: (sessionIds) => {
+    void isolateAsync('eval-js-end-flow', () => endEvalJsFlowSession(sessionIds), {
+      rethrowHostContract: false,
+    });
+  },
+  warn: (message) => {
+    console.warn(message);
+  },
+});

package/src/lifecycle.ts

@@ -49,7 +49,10 @@ export interface LifecycleControllerDeps {
    * Do not call while lifecycle-suspended — use {@link resume} instead.
    */
   ensureAlive: () => void;
-  /** True while any mid-flow session (live or draft/preview) is on screen. */
+  /**
+   * True while a mid-flow session is held, including one Temporarily Hide is
+   * suppressing. Idle suspend waits so a later attribute update can still unhide it.
+   */
   hasActiveSession: () => boolean;
   /**
    * Re-fire the current screen view after a real background (away past grace).

package/src/navigation/WithUserflowReactNavigation.tsx

@@ -7,6 +7,7 @@ import type {
 import { cloneElement, isValidElement, useCallback, useEffect, useRef } from 'react';
 import type React from 'react';
 
+import { isolateSync } from '../runtime/isolateCall';
 import { handleScreenChange } from '../screenTracker';
 
 import { chainCallbacks } from './chainCallbacks';
@@ -63,16 +64,18 @@ export function WithUserflowReactNavigation({
 
   const reportFocusedScreen = useCallback(
     (state?: NavigationState) => {
-      if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
-        overlayWasFocusedRef.current = true;
-        return;
-      }
-      const name = getActiveRouteName(state ?? navigationRef.getRootState());
-      handleScreenChange(
-        name ? { screen: name } : undefined,
-        overlayWasFocusedRef.current ? { force: true } : undefined,
-      );
-      overlayWasFocusedRef.current = false;
+      isolateSync('react-navigation-screen', () => {
+        if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
+          overlayWasFocusedRef.current = true;
+          return;
+        }
+        const name = getActiveRouteName(state ?? navigationRef.getRootState());
+        handleScreenChange(
+          name ? { screen: name } : undefined,
+          overlayWasFocusedRef.current ? { force: true } : undefined,
+        );
+        overlayWasFocusedRef.current = false;
+      });
     },
     [navigationRef],
   );

package/src/navigation/openFlowNavigateUrl.ts

@@ -2,6 +2,7 @@ import type { NavigationContainerRef, ParamListBase } from '@react-navigation/na
 import { Linking } from 'react-native';
 
 import { isSafeUrl, openSafeUrl } from '../content/openSafeUrl';
+import { isolateAsync, isolateSync } from '../runtime/isolateCall';
 
 export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
 
@@ -75,7 +76,9 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
   if (!trimmed) return;
 
   if (hostOnNavigate) {
-    await hostOnNavigate(trimmed);
+    await isolateAsync('onNavigate', async () => {
+      await hostOnNavigate!(trimmed);
+    });
     return;
   }
 
@@ -86,13 +89,17 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
 
   if (isInAppNavigateUrl(trimmed)) {
     if (expoRouter) {
-      expoRouter.push(normalizeInAppPath(trimmed));
+      isolateSync('onNavigate', () => {
+        expoRouter!.push(normalizeInAppPath(trimmed));
+      });
       return;
     }
     if (navigationRef?.isReady()) {
-      const name = routeNameFromPath(trimmed);
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
-      (navigationRef as NavigationContainerRef<ParamListBase>).navigate(name as any);
+      isolateSync('onNavigate', () => {
+        const name = routeNameFromPath(trimmed);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
+        (navigationRef as NavigationContainerRef<ParamListBase>).navigate(name as any);
+      });
       return;
     }
   }