@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/evalJs/EvalJsHost.tsx

@@ -0,0 +1,255 @@
+import * as React from 'react';
+import { Platform, useColorScheme, useWindowDimensions, View, type ViewStyle } from 'react-native';
+
+import { getCurrentScreenLocation, subscribeScreenLocation } from '../screenTracker';
+import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { buildBootstrapHtml, EVAL_JS_BASE_URL, isBootstrapUrl } from './bootstrap';
+import { parseBridgeMessage } from './bridgeMessages';
+import { formatEvalJsError, getEvalJsBridgeHandlers } from './evalJsBridge';
+import { evalJsController } from './evalJsController';
+import { getEvalJsWebView, type EvalJsWebViewHandle } from './getWebView';
+import type { EvalJsContext, EvalJsLayout, EvalJsScreen } from './types';
+import { useEvalJsWebViewInjection } from './useEvalJsWebViewInjection';
+
+export interface EvalJsHostProps {
+  /** Hide the page (picker is up) without destroying script state. */
+  suppressed: boolean;
+}
+
+function screenFromLocation(location: { path: string } | { screen: string } | null): EvalJsScreen {
+  if (!location) return {};
+  if ('path' in location) return location.path ? { path: location.path } : {};
+  return location.screen ? { name: location.screen } : {};
+}
+
+function useEvalJsScreen(): EvalJsScreen {
+  const [screen, setScreen] = React.useState<EvalJsScreen>(() =>
+    screenFromLocation(getCurrentScreenLocation()),
+  );
+  React.useEffect(() => {
+    return subscribeScreenLocation((location) => {
+      setScreen(screenFromLocation(location));
+    });
+  }, []);
+  return screen;
+}
+
+interface Clip {
+  interactive: boolean;
+  outer: ViewStyle;
+  web: ViewStyle;
+}
+
+function clipFor(
+  layout: EvalJsLayout,
+  viewport: { width: number; height: number },
+  suppressed: boolean,
+): Clip {
+  const fullWeb: ViewStyle = {
+    width: viewport.width,
+    height: viewport.height,
+    backgroundColor: 'transparent',
+  };
+  const hidden = suppressed || (layout.mode !== 'fitted' && layout.mode !== 'fullscreen');
+  if (hidden) {
+    return {
+      interactive: false,
+      outer: { ...ABSOLUTE_FILL, opacity: 0 },
+      web: fullWeb,
+    };
+  }
+  if (layout.mode === 'fullscreen') {
+    return { interactive: true, outer: ABSOLUTE_FILL, web: fullWeb };
+  }
+  const rect = layout.rect;
+  if (!rect) {
+    return {
+      interactive: false,
+      outer: { ...ABSOLUTE_FILL, opacity: 0 },
+      web: fullWeb,
+    };
+  }
+  return {
+    interactive: true,
+    outer: {
+      position: 'absolute',
+      left: rect.x,
+      top: rect.y,
+      width: rect.width,
+      height: rect.height,
+      overflow: 'hidden',
+    },
+    web: {
+      position: 'absolute',
+      left: -rect.x,
+      top: -rect.y,
+      width: viewport.width,
+      height: viewport.height,
+      backgroundColor: 'transparent',
+    },
+  };
+}
+
+/**
+ * One shared WebView for Evaluate JavaScript. Mounted by the SDK overlay,
+ * created on first use, destroyed on {@link evalJsController.reset}.
+ *
+ * Fitted mode clips a full-size WebView to the script's rectangle so the
+ * page viewport does not change (and the rest of the app still receives taps).
+ */
+export function EvalJsHost({ suppressed }: EvalJsHostProps): React.ReactElement | null {
+  const snapshot = React.useSyncExternalStore(
+    evalJsController.subscribe,
+    evalJsController.getSnapshot,
+    evalJsController.getSnapshot,
+  );
+  if (!snapshot.active) return null;
+  if (snapshot.bannerOwnsWebView) return null;
+  return (
+    <EvalJsWebView
+      key={snapshot.generation}
+      suppressed={suppressed}
+      generation={snapshot.generation}
+      pendingCount={snapshot.pendingCount}
+      layout={snapshot.layout}
+      host={snapshot.host}
+    />
+  );
+}
+
+interface WebViewProps {
+  suppressed: boolean;
+  generation: number;
+  pendingCount: number;
+  layout: EvalJsLayout;
+  host: Record<string, unknown>;
+}
+
+function EvalJsWebView({
+  suppressed,
+  generation,
+  pendingCount,
+  layout,
+  host,
+}: WebViewProps): React.ReactElement | null {
+  const WebView = getEvalJsWebView();
+  const webRef = React.useRef<EvalJsWebViewHandle>(null);
+  const [pageReady, setPageReady] = React.useState(false);
+  const generationRef = React.useRef(generation);
+  const colorScheme = useColorScheme();
+  const viewport = useWindowDimensions();
+  const insets = useUserflowSafeAreaInsets();
+  const screen = useEvalJsScreen();
+
+  const context = React.useMemo<EvalJsContext>(
+    () => ({
+      platform: Platform.OS,
+      colorScheme: colorScheme === 'dark' ? 'dark' : 'light',
+      safeAreaInsets: insets,
+      viewport: { width: viewport.width, height: viewport.height },
+      screen,
+      host,
+    }),
+    [colorScheme, host, insets, screen, viewport.height, viewport.width],
+  );
+
+  const initialContext = React.useRef(context);
+  const html = React.useMemo(() => buildBootstrapHtml(initialContext.current), []);
+
+  useEvalJsWebViewInjection(webRef, { pageReady, context, pendingCount });
+
+  const openExternal = React.useCallback((url: string) => {
+    if (!url || isBootstrapUrl(url)) return;
+    getEvalJsBridgeHandlers().openUrl(url);
+  }, []);
+
+  const onMessage = React.useCallback(
+    (event: { nativeEvent: { data?: string } }) => {
+      if (generationRef.current !== generation) return;
+      const message = parseBridgeMessage(event.nativeEvent.data);
+      if (!message) return;
+      const bridge = getEvalJsBridgeHandlers();
+      switch (message.type) {
+        case 'ready':
+          setPageReady(true);
+          return;
+        case 'close':
+          evalJsController.reset();
+          return;
+        case 'endFlow':
+          bridge.endFlow(evalJsController.sessionIds());
+          evalJsController.reset();
+          return;
+        case 'setLayout':
+          evalJsController.setLayout(message.layout);
+          return;
+        case 'track':
+          bridge.track(message.name, message.attributes);
+          return;
+        case 'updateUser':
+          bridge.updateUser(message.attributes);
+          return;
+        case 'updateGroup':
+          bridge.updateGroup(message.attributes, message.options);
+          return;
+        case 'openUrl':
+          bridge.openUrl(message.url);
+          return;
+        case 'error':
+          bridge.warn(formatEvalJsError(message.message, message.code));
+          return;
+        default:
+          return;
+      }
+    },
+    [generation],
+  );
+
+  if (!WebView) return null;
+
+  const clip = clipFor(layout, { width: viewport.width, height: viewport.height }, suppressed);
+  const debugging = typeof __DEV__ !== 'undefined' && __DEV__ ? true : undefined;
+
+  return (
+    <View pointerEvents="box-none" style={ABSOLUTE_FILL}>
+      <View pointerEvents={clip.interactive ? 'auto' : 'none'} style={clip.outer}>
+        <WebView
+          ref={webRef}
+          source={{ html, baseUrl: EVAL_JS_BASE_URL }}
+          style={clip.web}
+          pointerEvents={clip.interactive ? 'auto' : 'none'}
+          originWhitelist={['*']}
+          javaScriptEnabled
+          domStorageEnabled
+          scrollEnabled={false}
+          bounces={false}
+          showsHorizontalScrollIndicator={false}
+          showsVerticalScrollIndicator={false}
+          mediaPlaybackRequiresUserAction={false}
+          allowsInlineMediaPlayback
+          setSupportMultipleWindows={false}
+          androidLayerType="hardware"
+          {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
+          onMessage={onMessage}
+          onShouldStartLoadWithRequest={(request) => {
+            if (isBootstrapUrl(request.url)) return true;
+            openExternal(request.url);
+            return false;
+          }}
+          onOpenWindow={(event) => {
+            const url = event.nativeEvent.targetUrl;
+            if (url) openExternal(url);
+          }}
+          onError={(event) => {
+            const description = event.nativeEvent.description;
+            if (description) {
+              getEvalJsBridgeHandlers().warn(formatEvalJsError(description));
+            }
+          }}
+        />
+      </View>
+    </View>
+  );
+}

package/src/evalJs/bootstrap.ts

@@ -0,0 +1,83 @@
+import type { EvalJsContext } from './types';
+
+/** Document URL of the empty page that hosts customer scripts. */
+export const EVAL_JS_BASE_URL = 'https://userflow.local/';
+
+export function isBootstrapUrl(url: string): boolean {
+  if (!url || url === 'about:blank' || url.startsWith('about:blank')) return true;
+  if (url.startsWith('data:text/html')) return true;
+  return url === EVAL_JS_BASE_URL || url.startsWith(EVAL_JS_BASE_URL);
+}
+
+function embedJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+/**
+ * Empty transparent page plus the `window.userflow` bridge.
+ * The bridge runs in the document itself, before any customer code is injected.
+ */
+export function buildBootstrapHtml(context: EvalJsContext, bodyHtml = ''): string {
+  const contextJson = embedJson(context);
+  return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<style>
+  html, body { margin: 0; padding: 0; background: transparent; }
+</style>
+<script>
+(function () {
+  function post(msg) {
+    try {
+      if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
+        window.ReactNativeWebView.postMessage(JSON.stringify(Object.assign({ __userflow: 1 }, msg)));
+      }
+    } catch (e) {}
+  }
+  window.__userflowApplyContext = function (next) {
+    window.userflowContext = next || {};
+    try { window.dispatchEvent(new Event('userflow:contextchange')); } catch (e) {}
+  };
+  window.__userflowApplyContext(${contextJson});
+  window.userflow = {
+    track: function (name, attributes) { post({ type: 'track', name: name, attributes: attributes }); },
+    updateUser: function (attributes) { post({ type: 'updateUser', attributes: attributes }); },
+    updateGroup: function (attributes, options) { post({ type: 'updateGroup', attributes: attributes, options: options }); },
+    openUrl: function (url) { post({ type: 'openUrl', url: String(url || '') }); },
+    close: function () { post({ type: 'close' }); },
+    endFlow: function () { post({ type: 'endFlow' }); },
+    setLayout: function (layout) { post({ type: 'setLayout', layout: layout }); }
+  };
+  window.addEventListener('error', function (event) {
+    post({ type: 'error', message: String((event && event.message) || 'error') });
+  });
+  post({ type: 'ready' });
+})();
+</script>
+</head>
+<body>${bodyHtml}</body>
+</html>`;
+}
+
+/** Push a fresh `userflowContext` and notify scripts. Does not reload the page. */
+export function contextUpdateScript(context: EvalJsContext): string {
+  return `window.__userflowApplyContext&&window.__userflowApplyContext(${embedJson(context)});true;`;
+}
+
+/**
+ * Same execution model as web userflow.js: `new Function('"use strict";\\n' + code)`.
+ * The code is a JSON string literal so it cannot break out of the wrapper.
+ * `true;` is required so `injectJavaScript` settles on iOS.
+ */
+export function wrapCode(code: string): string {
+  const literal = embedJson(code);
+  return (
+    `try{var __uf=new Function('"use strict";\\n'+${literal});__uf();}` +
+    `catch(e){var __m=(e&&(e.stack||e.message))||String(e);` +
+    `if(window.ReactNativeWebView&&window.ReactNativeWebView.postMessage){` +
+    `window.ReactNativeWebView.postMessage(JSON.stringify({__userflow:1,type:'error',message:String(__m),code:${literal}}));}}` +
+    `true;`
+  );
+}

package/src/evalJs/bridgeMessages.ts

@@ -0,0 +1,134 @@
+import type { EvalJsLayout, EvalJsRect } from './types';
+
+const MESSAGE_TYPES = new Set([
+  'ready',
+  'close',
+  'endFlow',
+  'setLayout',
+  'track',
+  'updateUser',
+  'updateGroup',
+  'openUrl',
+  'error',
+]);
+
+export type BridgeMessage =
+  | { type: 'ready' }
+  | { type: 'close' }
+  | { type: 'endFlow' }
+  | { type: 'setLayout'; layout: EvalJsLayout }
+  | { type: 'track'; name: string; attributes?: Record<string, unknown> }
+  | { type: 'updateUser'; attributes: Record<string, unknown> }
+  | {
+      type: 'updateGroup';
+      attributes: Record<string, unknown>;
+      options?: { membership?: Record<string, unknown> };
+    }
+  | { type: 'openUrl'; url: string }
+  | { type: 'error'; message: string; code?: string };
+
+/**
+ * Accept only JSON objects tagged `__userflow: 1` with an allowlisted type.
+ * Anything else (page noise, unexpected shapes) is ignored.
+ */
+export function parseBridgeMessage(raw: unknown): BridgeMessage | null {
+  let value = raw;
+  if (typeof raw === 'string') {
+    try {
+      value = JSON.parse(raw) as unknown;
+    } catch {
+      return null;
+    }
+  }
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (record.__userflow !== 1) return null;
+  if (typeof record.type !== 'string' || !MESSAGE_TYPES.has(record.type)) return null;
+
+  switch (record.type) {
+    case 'ready':
+      return { type: 'ready' };
+    case 'close':
+      return { type: 'close' };
+    case 'endFlow':
+      return { type: 'endFlow' };
+    case 'error':
+      return {
+        type: 'error',
+        message: typeof record.message === 'string' ? record.message : 'error',
+        ...(typeof record.code === 'string' ? { code: record.code } : {}),
+      };
+    case 'openUrl':
+      if (typeof record.url !== 'string' || record.url.length === 0) return null;
+      return { type: 'openUrl', url: record.url };
+    case 'track': {
+      if (typeof record.name !== 'string' || record.name.length === 0) return null;
+      if (record.attributes != null && !isRecord(record.attributes)) return null;
+      return {
+        type: 'track',
+        name: record.name,
+        ...(isRecord(record.attributes) ? { attributes: record.attributes } : {}),
+      };
+    }
+    case 'updateUser': {
+      if (!isRecord(record.attributes)) return null;
+      return { type: 'updateUser', attributes: record.attributes };
+    }
+    case 'updateGroup': {
+      if (!isRecord(record.attributes)) return null;
+      const options = record.options;
+      if (options == null) return { type: 'updateGroup', attributes: record.attributes };
+      if (!isRecord(options)) return null;
+      if (options.membership != null && !isRecord(options.membership)) return null;
+      return {
+        type: 'updateGroup',
+        attributes: record.attributes,
+        ...(isRecord(options.membership) ? { options: { membership: options.membership } } : {}),
+      };
+    }
+    case 'setLayout': {
+      const layout = parseLayout(record.layout);
+      if (!layout) return null;
+      return { type: 'setLayout', layout };
+    }
+    default:
+      return null;
+  }
+}
+
+function parseLayout(value: unknown): EvalJsLayout | null {
+  if (!isRecord(value)) return null;
+  if (value.mode === 'hidden' || value.mode === 'fullscreen') {
+    return { mode: value.mode };
+  }
+  if (value.mode !== 'fitted') return null;
+  const rect = parseRect(value.rect);
+  if (!rect) return null;
+  return { mode: 'fitted', rect };
+}
+
+function parseRect(value: unknown): EvalJsRect | null {
+  if (!isRecord(value)) return null;
+  const x = value.x;
+  const y = value.y;
+  const width = value.width;
+  const height = value.height;
+  if (
+    !isFiniteNumber(x) ||
+    !isFiniteNumber(y) ||
+    !isFiniteNumber(width) ||
+    !isFiniteNumber(height)
+  ) {
+    return null;
+  }
+  if (width <= 0 || height <= 0) return null;
+  return { x, y, width, height };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}

package/src/evalJs/evalJsBridge.ts

@@ -0,0 +1,42 @@
+/** Calls into the public SDK without importing the facade (that would cycle). */
+export interface EvalJsBridgeHandlers {
+  track(name: string, attributes?: Record<string, unknown>): void;
+  updateUser(attributes: Record<string, unknown>): void;
+  updateGroup(
+    attributes: Record<string, unknown>,
+    options?: { membership?: Record<string, unknown> },
+  ): void;
+  openUrl(url: string): void;
+  /** End the current flow session if it is one of `sessionIds` (the scripts in this WebView). */
+  endFlow(sessionIds: ReadonlySet<string>): void;
+  warn(message: string): void;
+}
+
+const noopHandlers: EvalJsBridgeHandlers = {
+  track: () => undefined,
+  updateUser: () => undefined,
+  updateGroup: () => undefined,
+  openUrl: () => undefined,
+  endFlow: () => undefined,
+  warn: (message) => {
+    console.warn(message);
+  },
+};
+
+let handlers: EvalJsBridgeHandlers = noopHandlers;
+
+export function setEvalJsBridgeHandlers(next: EvalJsBridgeHandlers | null): void {
+  handlers = next ?? noopHandlers;
+}
+
+export function getEvalJsBridgeHandlers(): EvalJsBridgeHandlers {
+  return handlers;
+}
+
+export function formatEvalJsError(message: string, code?: string): string {
+  return (
+    `Userflow: Evaluate JavaScript action failed.\n\n` +
+    `Error:\n${message}\n\n` +
+    `Code:\n${code ?? ''}`
+  );
+}

package/src/evalJs/evalJsController.ts

@@ -0,0 +1,127 @@
+import type { EvalJsEnqueueRequest, EvalJsLayout, EvalJsSnapshot } from './types';
+
+const HIDDEN: EvalJsLayout = { mode: 'hidden' };
+
+type Listener = () => void;
+
+let generation = 0;
+let active = false;
+let pending: string[] = [];
+/** Sessions whose scripts ran in the current WebView; `endFlow` may only end one of these. */
+let sessionIds = new Set<string>();
+let layout: EvalJsLayout = HIDDEN;
+let host: Record<string, unknown> = {};
+let bannerOwnsWebView = false;
+const listeners = new Set<Listener>();
+
+/**
+ * Cached for `useSyncExternalStore`: React re-renders forever if getSnapshot
+ * returns a new object while nothing changed.
+ */
+let currentSnapshot: EvalJsSnapshot = {
+  active,
+  generation,
+  pendingCount: 0,
+  layout,
+  host,
+  bannerOwnsWebView,
+};
+
+function emit(): void {
+  currentSnapshot = {
+    active,
+    generation,
+    pendingCount: pending.length,
+    layout,
+    host,
+    bannerOwnsWebView,
+  };
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+export const evalJsController = {
+  subscribe(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+
+  getSnapshot(): EvalJsSnapshot {
+    return currentSnapshot;
+  },
+
+  enqueue(request: EvalJsEnqueueRequest): void {
+    if (!request.code) return;
+    pending = [...pending, request.code];
+    sessionIds.add(request.sessionId);
+    active = true;
+    emit();
+  },
+
+  sessionIds(): ReadonlySet<string> {
+    return new Set(sessionIds);
+  },
+
+  /** Codes waiting to be injected. Clears the queue. */
+  consumePending(): string[] {
+    if (pending.length === 0) return [];
+    const codes = pending;
+    pending = [];
+    emit();
+    return codes;
+  },
+
+  setLayout(next: EvalJsLayout): void {
+    layout = next;
+    emit();
+  },
+
+  /** App-supplied values exposed as `userflowContext.host`. Survives reset. */
+  setHostContext(values: Record<string, unknown>): void {
+    host = { ...values };
+    emit();
+  },
+
+  /** Custom banner WebView is the sole eval page (no overlay EvalJsHost). */
+  setBannerOwnsWebView(owns: boolean): void {
+    bannerOwnsWebView = owns;
+    emit();
+  },
+
+  /**
+   * Destroy the shared WebView and drop queued code. Host context stays so the
+   * next script still sees language / tab-bar height the app provided.
+   */
+  reset(): void {
+    generation += 1;
+    active = false;
+    pending = [];
+    sessionIds = new Set();
+    layout = HIDDEN;
+    bannerOwnsWebView = false;
+    emit();
+  },
+};
+
+/** @internal */
+export function resetEvalJsControllerForTests(): void {
+  generation = 0;
+  active = false;
+  pending = [];
+  sessionIds = new Set();
+  layout = HIDDEN;
+  host = {};
+  bannerOwnsWebView = false;
+  listeners.clear();
+  currentSnapshot = {
+    active,
+    generation,
+    pendingCount: 0,
+    layout,
+    host,
+    bannerOwnsWebView,
+  };
+}