@dynamic-labs/react-native-extension 4.83.1 → 4.84.0

package/index.cjs

@@ -8,12 +8,13 @@ var react = require('react');
 var reactNativeWebview = require('react-native-webview');
 var logger$1 = require('@dynamic-labs/logger');
 var messageTransport = require('@dynamic-labs/message-transport');
+var webviewMessages = require('@dynamic-labs/webview-messages');
+var expoSecureStore = require('expo-secure-store');
 var jsxRuntime = require('react/jsx-runtime');
 var expoModulesCore = require('expo-modules-core');
 var reactNativePasskey = require('react-native-passkey');
 var expoLinking = require('expo-linking');
 var expoWebBrowser = require('expo-web-browser');
-var expoSecureStore = require('expo-secure-store');
 var reactNativePasskeyStamper = require('@turnkey/react-native-passkey-stamper');
 
 function _interopNamespace(e) {
@@ -34,7 +35,7 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var version = "4.83.1";
+var version = "4.84.0";
 
 function _extends() {
   return _extends = Object.assign ? Object.assign.bind() : function (n) {
@@ -122,6 +123,396 @@ const useMessageTransportWebViewBridge = (core, webViewRef) => {
   };
 };
 
+const CLEAR_STATE_PARAM = 'clear-state';
+const ENVIRONMENT_ID_PARAM = 'environmentId';
+const WEBVIEW_START_TIME_PARAM = 'webviewStartTime';
+
+const hasClearStateInUrl = webViewUrl => Boolean(webViewUrl.searchParams.get(CLEAR_STATE_PARAM));
+
+/**
+ * Wire-format `type` of a webview-side `manifest` request.
+ *
+ * `requestChannel.request('manifest')` sends a `MessageTransportData` whose
+ * `type` is the literal request name. The host replies with `manifest__ack`,
+ * which we ignore: receiving the request is sufficient evidence that the
+ * webview JS bundle is alive and the message bridge works.
+ */
+const MANIFEST_MESSAGE_TYPE = 'manifest';
+const emptyTimings = () => ({
+  htmlLoadStartedAt: null,
+  htmlLoadedAt: null,
+  manifestReceivedAt: null,
+  onLoadEndAt: null,
+  sdkReadyAt: null
+});
+const diffMs = (later, earlier) => later !== null && earlier !== null ? later - earlier : null;
+/**
+ * Derive cross-phase durations from raw timestamps. The four durations
+ * are what end up in the failure / success log meta:
+ *
+ * - `htmlLoadMs` — `onLoadStart` to `onLoad`; native HTML fetch
+ * - `onLoadToOnLoadEndMs` — `onLoad` to `onLoadEnd`; native render/parse
+ * - `manifestReceivedMs` — `onLoadEnd` to first `manifest` request from
+ *   the webview JS; "JS bundle is alive" signal
+ * - `sdkReadyMs` — `onLoadEnd` to first `sdkHasLoaded` event from the
+ *   webview JS; "SDK fully bootstrapped" signal
+ */
+const computePhaseDurations = timings => ({
+  htmlLoadMs: diffMs(timings.htmlLoadedAt, timings.htmlLoadStartedAt),
+  manifestReceivedMs: diffMs(timings.manifestReceivedAt, timings.onLoadEndAt),
+  onLoadToOnLoadEndMs: diffMs(timings.onLoadEndAt, timings.htmlLoadedAt),
+  sdkReadyMs: diffMs(timings.sdkReadyAt, timings.onLoadEndAt)
+});
+/**
+ * Build the success-shape meta from a {@link WebViewPhaseTimerCore}
+ * snapshot plus the path-specific fields. Both call sites call this
+ * with their own context (RN reads `hadClearState` / `retryCount` from
+ * the URL; embedded passes constants) so the success-log payload stays
+ * identical across the two paths.
+ */
+const buildSuccessMeta = ({
+  core,
+  hadClearState,
+  loadingTimeoutMs,
+  recoveryTimeoutMs,
+  retryCount,
+  webviewUrl
+}) => Object.assign(Object.assign({
+  hadClearState,
+  loadingTimeoutMs,
+  recoveryTimeoutMs,
+  retryCount,
+  webviewUrl
+}, computePhaseDurations(core.getTimings())), core.getCounters());
+/**
+ * Shared state machine driving WebView load-phase instrumentation.
+ *
+ * Both the React `<WebView>` (RN bridge) and the native embedded WebView
+ * (native bridge) feed lifecycle events into this core and produce
+ * matching meta from the same timings + counters. Each path layers its
+ * own path-specific fields (`hadClearState`, `retryCount`, etc.) on top
+ * of the raw state this core exposes via `getTimings()` / `getCounters()`.
+ *
+ * The core owns the `core.messageTransport` subscription that captures
+ * the two webview-originated signals bracketing SDK bootstrap
+ * (`manifest` once the JS bundle is alive; `sdkHasLoadedEventName`
+ * once the SDK is fully ready). Native bridge lifecycle events come in
+ * via `recordEvent` instead.
+ */
+const createWebViewPhaseTimerCore = ({
+  core
+}) => {
+  let timings = emptyTimings();
+  let nativeErrorCount = 0;
+  let osKillCount = 0;
+  /**
+   * We only capture the first occurrence per attempt so that a healthy
+   * reload doesn't overwrite the timing from the attempt that ultimately
+   * failed.
+   */
+  const handleMessage = message => {
+    if (message.origin !== 'webview') return;
+    if (message.type === MANIFEST_MESSAGE_TYPE && timings.manifestReceivedAt === null) {
+      timings.manifestReceivedAt = Date.now();
+    }
+    if (message.type === webviewMessages.sdkHasLoadedEventName && timings.sdkReadyAt === null) {
+      timings.sdkReadyAt = Date.now();
+    }
+  };
+  core.messageTransport.on(handleMessage);
+  return {
+    dispose: () => {
+      core.messageTransport.off(handleMessage);
+    },
+    getCounters: () => ({
+      nativeErrorCount,
+      osKillCount
+    }),
+    getTimings: () => timings,
+    recordEvent: event => {
+      const now = Date.now();
+      switch (event) {
+        case 'load_start':
+          timings = emptyTimings();
+          timings.htmlLoadStartedAt = now;
+          break;
+        case 'load':
+          timings.htmlLoadedAt = now;
+          break;
+        case 'load_end':
+          timings.onLoadEndAt = now;
+          break;
+        case 'native_error':
+          nativeErrorCount += 1;
+          break;
+        case 'os_kill':
+          osKillCount += 1;
+          break;
+      }
+    }
+  };
+};
+
+const RETRY_QUERY_PARAM = 'retry';
+const readRetryCount = webViewUrl => {
+  const raw = webViewUrl.searchParams.get(RETRY_QUERY_PARAM);
+  if (raw === null) return 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Snapshot returned by the phase-timer core when it hasn't been
+ * instantiated yet (briefly true between hook construction and the
+ * `useEffect` running). Lets `getSuccessMeta` / `getMeta` produce a
+ * well-formed empty meta in that window without special-casing each
+ * field.
+ */
+const EMPTY_CORE_SNAPSHOT = {
+  getCounters: () => ({
+    nativeErrorCount: 0,
+    osKillCount: 0
+  }),
+  getTimings: () => ({
+    htmlLoadStartedAt: null,
+    htmlLoadedAt: null,
+    manifestReceivedAt: null,
+    onLoadEndAt: null,
+    sdkReadyAt: null
+  })
+};
+/**
+ * Tracks how long each step of the WebView load took, so when we raise
+ * `WebViewFailedToLoadError` we can attach the timings to the error log.
+ *
+ * The timings cover the host-side phases of the load — the webview-side
+ * timings (`webview.time_to_load_manifest`, `webview.time_to_sdk_ready`)
+ * still come from the webview itself once it boots, but those don't help
+ * when the webview never boots in the first place.
+ *
+ * The actual state machine lives in {@link createWebViewPhaseTimerCore},
+ * which is also reused by the embedded native WebView path. This hook
+ * only layers the React-specific bits (ref-based core lifetime tied to
+ * `useEffect`, URL-derived `hadClearState` / `retryCount`).
+ */
+const useWebViewPhaseTimers = ({
+  core,
+  loadingTimeout,
+  recoveryTimeout,
+  webViewUrl
+}) => {
+  const phaseCoreRef = react.useRef(null);
+  const webViewUrlRef = react.useRef(webViewUrl);
+  webViewUrlRef.current = webViewUrl;
+  /**
+   * Owning the message-transport subscription in `useEffect` matches the
+   * lifetime semantics any other React subscription would have, and lets
+   * us cleanly re-subscribe if `core` is ever swapped at runtime.
+   */
+  react.useEffect(() => {
+    const phaseCore = createWebViewPhaseTimerCore({
+      core
+    });
+    phaseCoreRef.current = phaseCore;
+    return () => {
+      phaseCore.dispose();
+      if (phaseCoreRef.current === phaseCore) {
+        phaseCoreRef.current = null;
+      }
+    };
+  }, [core]);
+  const recordEvent = react.useCallback(event => {
+    var _a;
+    (_a = phaseCoreRef.current) === null || _a === void 0 ? void 0 : _a.recordEvent(event);
+  }, []);
+  const getSuccessMeta = react.useCallback(() => {
+    var _a;
+    const url = webViewUrlRef.current;
+    return buildSuccessMeta({
+      core: (_a = phaseCoreRef.current) !== null && _a !== void 0 ? _a : EMPTY_CORE_SNAPSHOT,
+      hadClearState: hasClearStateInUrl(url),
+      loadingTimeoutMs: loadingTimeout,
+      recoveryTimeoutMs: recoveryTimeout,
+      retryCount: readRetryCount(url),
+      webviewUrl: url.toString()
+    });
+  }, [loadingTimeout, recoveryTimeout]);
+  const getMeta = react.useCallback(({
+    phase
+  }) => Object.assign(Object.assign({}, getSuccessMeta()), {
+    phase
+  }), [getSuccessMeta]);
+  return {
+    getMeta,
+    getSuccessMeta,
+    recordEvent
+  };
+};
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+const SUCCESS_LOG_KEY = 'webview.load_succeeded';
+/**
+ * Shared emission pattern for the `webview.load_succeeded`
+ * instrumentation log. Both the RN `<WebView>` and the embedded
+ * WebView fire the same event with the same payload shape after
+ * checking the same cooldown gate — this helper centralises that
+ * sequence so the two call sites stay aligned and any future field we
+ * add to the success log lands in both places automatically.
+ */
+const emitSuccessLog = _a => __awaiter(void 0, [_a], void 0, function* ({
+  cooldown,
+  core,
+  getMeta,
+  name
+}) {
+  if (!(yield cooldown.shouldEmit())) return;
+  logger.instrument(`${name} loaded successfully`, Object.assign({
+    environmentId: core.environmentId,
+    hostSdkSessionId: core.hostSdkSessionId,
+    key: SUCCESS_LOG_KEY,
+    time: 0
+  }, getMeta()));
+  yield cooldown.recordEmitted();
+});
+
+const SUCCESS_LOG_COOLDOWN_MS = 60 * 60 * 1000;
+const parseStoredTimestamp = raw => {
+  if (raw === null) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+/**
+ * Create a device-local cooldown gate for a `webview.load_succeeded`
+ * instrumentation log.
+ *
+ * Both `<WebView>` (RN bridge) and `<EmbeddedWebView>` (native bridge)
+ * emit the same success log; each instantiates its own cooldown with a
+ * dedicated storage key so emitting one log doesn't starve the other
+ * for an app that mounts both.
+ *
+ * - `shouldEmit` returns `true` when the cooldown has elapsed (or no
+ *   timestamp has ever been stored) and `false` while inside the
+ *   window. If secure-store throws on read we default to emitting —
+ *   losing a diagnostic log is worse than the rare duplicate.
+ * - `recordEmitted` persists the current timestamp so subsequent calls
+ *   within the window are suppressed. Write failures are swallowed
+ *   (logged as a warning) so they don't break the host wrapper —
+ *   worst case the next emit also goes through.
+ */
+const createSuccessLogCooldown = ({
+  name,
+  storageKey
+}) => ({
+  recordEmitted: (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (now = Date.now()) {
+    try {
+      yield expoSecureStore.setItemAsync(storageKey, now.toString());
+    } catch (error) {
+      logger.warn(`Failed to persist ${name} success-log cooldown timestamp`, {
+        error: String(error)
+      });
+    }
+  }),
+  shouldEmit: (...args_2) => __awaiter(void 0, [...args_2], void 0, function* (now = Date.now()) {
+    try {
+      const raw = yield expoSecureStore.getItemAsync(storageKey);
+      const lastEmittedAt = parseStoredTimestamp(raw);
+      if (lastEmittedAt === null) return true;
+      return now - lastEmittedAt >= SUCCESS_LOG_COOLDOWN_MS;
+    } catch (error) {
+      logger.warn(`Failed to read ${name} success-log cooldown timestamp; emitting anyway`, {
+        error: String(error)
+      });
+      return true;
+    }
+  })
+});
+
+const SUCCESS_LOG_COOLDOWN_STORAGE_KEY = 'dynamic.webview.successLogLastEmittedAt';
+/**
+ * Emit a `webview.load_succeeded` instrumentation log the first time
+ * the SDK signals it's ready, gated by a device-local 1h cooldown so a
+ * customer with many WebView mounts (or many app launches) doesn't spam
+ * the logs pipeline.
+ *
+ * The error path is unaffected: failures keep going through
+ * `logger.error(WebViewFailedToLoadError, meta)` with no cooldown.
+ *
+ * The hook intentionally fires only once per mount (`hasEmittedRef`):
+ * after a successful boot we don't expect another `sdkHasLoaded` for
+ * the same WebView lifetime, and emitting twice for the same load would
+ * be misleading.
+ *
+ * Cooldown gating + log emission are delegated to the shared
+ * `successLog` helpers so this hook and the embedded native WebView
+ * path stay in lockstep on payload shape and storage semantics; the
+ * dedicated storage key here keeps the RN-path cooldown independent
+ * from the embedded path's.
+ */
+const useWebViewSuccessLog = ({
+  core,
+  getSuccessMeta
+}) => {
+  const hasEmittedRef = react.useRef(false);
+  const getSuccessMetaRef = react.useRef(getSuccessMeta);
+  getSuccessMetaRef.current = getSuccessMeta;
+  react.useEffect(() => {
+    const cooldown = createSuccessLogCooldown({
+      name: 'webview',
+      storageKey: SUCCESS_LOG_COOLDOWN_STORAGE_KEY
+    });
+    const handler = message => __awaiter(void 0, void 0, void 0, function* () {
+      if (message.origin !== 'webview') return;
+      if (message.type !== webviewMessages.sdkHasLoadedEventName) return;
+      if (hasEmittedRef.current) return;
+      hasEmittedRef.current = true;
+      try {
+        yield emitSuccessLog({
+          cooldown,
+          core,
+          getMeta: getSuccessMetaRef.current,
+          name: 'Webview'
+        });
+      } catch (err) {
+        logger.warn('useWebViewSuccessLog.emitSuccessLog failed', {
+          error: String(err)
+        });
+      }
+    });
+    core.messageTransport.on(handler);
+    return () => {
+      core.messageTransport.off(handler);
+    };
+  }, [core]);
+};
+
 const useWebViewVisibility = core => {
   const webViewVisibilityRequestChannelRef = react.useRef(messageTransport.createRequestChannel(core.messageTransport));
   const [visible, setVisible] = react.useState(false);
@@ -158,10 +549,6 @@ const styles = reactNative.StyleSheet.create({
   }
 });
 
-const CLEAR_STATE_PARAM = 'clear-state';
-const ENVIRONMENT_ID_PARAM = 'environmentId';
-const WEBVIEW_START_TIME_PARAM = 'webviewStartTime';
-
 const setClearStateToUrl = webViewUrl => {
   const newWebViewUrl = new URL(webViewUrl);
   newWebViewUrl.searchParams.set(CLEAR_STATE_PARAM, 'true');
@@ -169,8 +556,6 @@ const setClearStateToUrl = webViewUrl => {
   return newWebViewUrl;
 };
 
-const hasClearStateInUrl = webViewUrl => Boolean(webViewUrl.searchParams.get(CLEAR_STATE_PARAM));
-
 const useWebViewRecoveryTimeout = ({
   core,
   webViewUrl,
@@ -323,15 +708,15 @@ const shouldAllowNavigation = (request, webViewUrl) => {
   return false;
 };
 
-const DEFAULT_RECOVERY_TIMEOUT_MS = 20000;
-const DEFAULT_LOADING_TIMEOUT_MS = 20000;
+const DEFAULT_RECOVERY_TIMEOUT_MS$1 = 20000;
+const DEFAULT_LOADING_TIMEOUT_MS$1 = 20000;
 const WebView = ({
   webviewUrl: initialWebViewUrl,
   core,
   webviewDebuggingEnabled: _webviewDebuggingEnabled = false,
   disableRecovery: _disableRecovery = false,
-  recoveryTimeout: _recoveryTimeout = DEFAULT_RECOVERY_TIMEOUT_MS,
-  loadingTimeout: _loadingTimeout = DEFAULT_LOADING_TIMEOUT_MS
+  recoveryTimeout: _recoveryTimeout = DEFAULT_RECOVERY_TIMEOUT_MS$1,
+  loadingTimeout: _loadingTimeout = DEFAULT_LOADING_TIMEOUT_MS$1
 }) => {
   const webViewRef = react.useRef(null);
   const {
@@ -341,6 +726,20 @@ const WebView = ({
   const {
     onMessageHandler
   } = useMessageTransportWebViewBridge(core, webViewRef);
+  const {
+    recordEvent,
+    getMeta,
+    getSuccessMeta
+  } = useWebViewPhaseTimers({
+    core,
+    loadingTimeout: _loadingTimeout,
+    recoveryTimeout: _recoveryTimeout,
+    webViewUrl
+  });
+  useWebViewSuccessLog({
+    core,
+    getSuccessMeta
+  });
   const containerStyles = [styles['container'], visible ? styles.show : styles.hide];
   /**
    * Block the message transport when the webview is unmounted
@@ -382,13 +781,23 @@ const WebView = ({
       return newWebViewUrl;
     });
   }, [core]);
-  const blockAndReloadWebViewOsKill = react.useCallback(() => blockAndReloadWebView('os_kill'), [blockAndReloadWebView]);
+  const blockAndReloadWebViewOsKill = react.useCallback(() => {
+    recordEvent('os_kill');
+    blockAndReloadWebView('os_kill');
+  }, [blockAndReloadWebView, recordEvent]);
   react.useEffect(() => core.messageTransport.recoveryManager.onRecoveryRequested(() => blockAndReloadWebView('recovery')), [core, blockAndReloadWebView]);
-  const setWebViewLoadError = react.useCallback(() => {
+  const setWebViewLoadError = react.useCallback(phase => {
     // Error was already thrown, do not throw again
     if (core.initialization.error instanceof WebViewFailedToLoadError) return;
-    core.initialization.error = new WebViewFailedToLoadError();
-  }, [core]);
+    core.initialization.error = new WebViewFailedToLoadError(getMeta({
+      phase
+    }));
+  }, [core, getMeta]);
+  /**
+   * Wraps `setWebViewLoadError` so the consumer doesn't need to know
+   * about the phase enum; each callsite below binds its own phase.
+   */
+  const setWebViewLoadErrorWithPhase = react.useCallback(phase => () => setWebViewLoadError(phase), [setWebViewLoadError]);
   /**
    * Reload the webview with a clean state when a timeout is reached
    * and the webview did not get to the loaded state yet
@@ -396,7 +805,7 @@ const WebView = ({
   const startRecoveryTimeout = useWebViewRecoveryTimeout({
     core,
     disableRecovery: _disableRecovery,
-    onFailedToLoadAfterClearState: setWebViewLoadError,
+    onFailedToLoadAfterClearState: setWebViewLoadErrorWithPhase('after_clear_state'),
     recoveryTimeout: _recoveryTimeout,
     setWebViewUrl,
     webViewUrl
@@ -404,26 +813,40 @@ const WebView = ({
   const webViewLoadErrorCountRef = react.useRef(0);
   const onWebViewLoadError = react.useCallback(() => {
     webViewLoadErrorCountRef.current = webViewLoadErrorCountRef.current + 1;
+    recordEvent('native_error');
     /**
      * This is the first attempt to load the webview, do not throw an error
      * because the recovery system will attempt to reload the webview
      */
     if (webViewLoadErrorCountRef.current === 1) return;
-    setWebViewLoadError();
-  }, [setWebViewLoadError]);
+    setWebViewLoadError('native_error');
+  }, [recordEvent, setWebViewLoadError]);
   const {
-    onLoad,
-    onLoadStart
-  } = useWebViewLoadingTimeout(_loadingTimeout, setWebViewLoadError);
+    onLoad: onLoadFromTimeout,
+    onLoadStart: onLoadStartFromTimeout
+  } = useWebViewLoadingTimeout(_loadingTimeout, setWebViewLoadErrorWithPhase('html_load'));
+  const onLoadStart = react.useCallback(() => {
+    recordEvent('load_start');
+    onLoadStartFromTimeout();
+  }, [onLoadStartFromTimeout, recordEvent]);
+  const onLoad = react.useCallback(() => {
+    recordEvent('load');
+    onLoadFromTimeout();
+  }, [onLoadFromTimeout, recordEvent]);
+  const onLoadEnd = react.useCallback(() => {
+    recordEvent('load_end');
+    startRecoveryTimeout();
+  }, [recordEvent, startRecoveryTimeout]);
+  const webViewUrlString = react.useMemo(() => webViewUrl.toString(), [webViewUrl]);
   return /*#__PURE__*/jsxRuntime.jsx(reactNativeWebview.WebView, {
     ref: webViewRef,
     source: {
-      uri: webViewUrl.toString()
+      uri: webViewUrlString
     },
     containerStyle: containerStyles,
     style: styles['webview'],
     onMessage: onMessageHandler,
-    onLoadEnd: () => startRecoveryTimeout(),
+    onLoadEnd: onLoadEnd,
     onLoadStart: onLoadStart,
     onLoad: onLoad,
     hideKeyboardAccessoryView: true,
@@ -436,7 +859,7 @@ const WebView = ({
       isTopFrame: request.isTopFrame,
       url: request.url
     }, webViewUrl)
-  });
+  }, webViewUrlString);
 };
 const createWebView = internalProps => {
   const WebViewWrapper = props => /*#__PURE__*/jsxRuntime.jsx(WebView, _extends({}, internalProps, props));
@@ -475,6 +898,53 @@ const getEmbeddedWebView = () => {
   }
 };
 
+/**
+ * Non-React equivalent of `useWebViewPhaseTimers` for the embedded native
+ * webview path. The embedded path is a singleton wired by
+ * `setupEmbeddedWebView` (not a React component), so we expose the same
+ * phase-timing surface as a plain factory.
+ *
+ * Both this factory and the hook delegate the actual state machine to
+ * {@link createWebViewPhaseTimerCore}; the only path-specific bits are:
+ *
+ * - `hadClearState` is always `false` (embedded path has no clear-state
+ *   recovery model — that's exclusive to the React `<WebView>` path's
+ *   loading-timeout recovery flow)
+ * - `retryCount` is always `0` (embedded path has no retry counter URL
+ *   query param either)
+ */
+const createEmbeddedWebViewPhaseTimers = ({
+  core,
+  loadingTimeoutMs,
+  recoveryTimeoutMs,
+  webViewUrl
+}) => {
+  const phaseCore = createWebViewPhaseTimerCore({
+    core
+  });
+  const getSuccessMeta = () => buildSuccessMeta({
+    core: phaseCore,
+    hadClearState: false,
+    loadingTimeoutMs,
+    recoveryTimeoutMs,
+    retryCount: 0,
+    webviewUrl: webViewUrl.toString()
+  });
+  return {
+    dispose: phaseCore.dispose,
+    getMeta: ({
+      phase
+    }) => Object.assign(Object.assign({}, getSuccessMeta()), {
+      phase
+    }),
+    getSuccessMeta,
+    recordEvent: phaseCore.recordEvent
+  };
+};
+
+const EMBEDDED_SUCCESS_LOG_COOLDOWN_STORAGE_KEY = 'dynamic.embeddedWebView.successLogLastEmittedAt';
+const DEFAULT_LOADING_TIMEOUT_MS = 20000;
+const DEFAULT_RECOVERY_TIMEOUT_MS = 20000;
 // Wires the JS-side bridge to the native WKWebView singleton owned by Swift.
 // This is intentionally not a React component: the embedded webview lives
 // outside the React tree (in a dedicated UIWindow on iOS), so its setup runs
@@ -487,10 +957,52 @@ const getEmbeddedWebView = () => {
 const setupEmbeddedWebView = ({
   webviewUrl,
   core,
-  webviewDebuggingEnabled: _webviewDebuggingEnabled = false
+  webviewDebuggingEnabled: _webviewDebuggingEnabled = false,
+  loadingTimeoutMs: _loadingTimeoutMs = DEFAULT_LOADING_TIMEOUT_MS,
+  recoveryTimeoutMs: _recoveryTimeoutMs = DEFAULT_RECOVERY_TIMEOUT_MS
 }) => {
   const native = getEmbeddedWebView();
   const builtUrl = assignStartTimeToUrl(assignEnvironmentIdToUrl(webviewUrl, core.environmentId));
+  const phaseTimers = createEmbeddedWebViewPhaseTimers({
+    core,
+    loadingTimeoutMs: _loadingTimeoutMs,
+    recoveryTimeoutMs: _recoveryTimeoutMs,
+    webViewUrl: builtUrl
+  });
+  const successLogCooldown = createSuccessLogCooldown({
+    name: 'embedded webview',
+    storageKey: EMBEDDED_SUCCESS_LOG_COOLDOWN_STORAGE_KEY
+  });
+  let loadingTimer = null;
+  let recoveryTimer = null;
+  let hasFailed = false;
+  let hasEmittedSuccessLog = false;
+  const clearLoadingTimer = () => {
+    if (loadingTimer !== null) {
+      clearTimeout(loadingTimer);
+      loadingTimer = null;
+    }
+  };
+  const clearRecoveryTimer = () => {
+    if (recoveryTimer !== null) {
+      clearTimeout(recoveryTimer);
+      recoveryTimer = null;
+    }
+  };
+  // Raise `WebViewFailedToLoadError` once per setup. Subsequent triggers
+  // (e.g. recovery timeout firing after html_load already failed) are
+  // suppressed so we don't spam the initialization-error setter with
+  // duplicate logs for the same load attempt.
+  const raiseFailure = (phase, extraMeta = {}) => {
+    if (hasFailed) return;
+    hasFailed = true;
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    const meta = phaseTimers.getMeta({
+      phase
+    });
+    core.initialization.error = new WebViewFailedToLoadError(Object.assign(Object.assign({}, meta), extraMeta));
+  };
   const visibilityChannel = messageTransport.createRequestChannel(core.messageTransport);
   const removeVisibilityHandler = visibilityChannel.handle('setVisibility', visible => {
     native.setVisible(visible).catch(err => {
@@ -504,6 +1016,30 @@ const setupEmbeddedWebView = ({
     });
   };
   core.messageTransport.on(handleHostMessage);
+  // Watch for the webview-side SDK ready signal so we can clear the
+  // recovery timer and emit the success log. The phase-timer factory
+  // also subscribes for its own bookkeeping — both subscriptions are
+  // independent and idempotent. The factory subscribes first and so
+  // sees `sdkReadyAt` before this handler runs, which means the meta
+  // we emit below has the freshest `sdkReadyMs`. We only emit once
+  // per setup; a second SDK-ready event for the same load wouldn't
+  // represent a new successful boot.
+  const handleSdkReady = message => {
+    if (message.origin !== 'webview') return;
+    if (message.type !== webviewMessages.sdkHasLoadedEventName) return;
+    clearRecoveryTimer();
+    if (hasEmittedSuccessLog || hasFailed) return;
+    hasEmittedSuccessLog = true;
+    emitSuccessLog({
+      cooldown: successLogCooldown,
+      core,
+      getMeta: phaseTimers.getSuccessMeta,
+      name: 'Embedded webview'
+    }).catch(err => {
+      logger.warn('EmbeddedWebView.emitSuccessLog failed', err);
+    });
+  };
+  core.messageTransport.on(handleSdkReady);
   const onMessageSub = native.addListener('onMessage', event => {
     let parsed = null;
     try {
@@ -526,7 +1062,32 @@ const setupEmbeddedWebView = ({
       logger.warn('EmbeddedWebView.respondToShouldStartLoad failed', err);
     });
   });
+  const onLoadStartSub = native.addListener('onLoadStart', () => {
+    phaseTimers.recordEvent('load_start');
+    // Re-arm both timers on every load_start. A retry from the native
+    // side (e.g. a redirect, or a reload after a transient failure)
+    // resets the html_load window cleanly without leaving a stale timer
+    // around from the previous attempt.
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    loadingTimer = setTimeout(() => {
+      raiseFailure('html_load');
+    }, _loadingTimeoutMs);
+  });
+  const onLoadSub = native.addListener('onLoad', () => {
+    phaseTimers.recordEvent('load');
+    clearLoadingTimer();
+  });
+  const onLoadEndSub = native.addListener('onLoadEnd', () => {
+    phaseTimers.recordEvent('load_end');
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    recoveryTimer = setTimeout(() => {
+      raiseFailure('sdk_bootstrap');
+    }, _recoveryTimeoutMs);
+  });
   const onLoadErrorSub = native.addListener('onLoadError', event => {
+    phaseTimers.recordEvent('native_error');
     logger.warn('EmbeddedWebView load error', event);
     logger.instrument('Embedded webview load error', {
       environmentId: core.environmentId,
@@ -540,7 +1101,13 @@ const setupEmbeddedWebView = ({
       time: 0,
       webviewUrl: builtUrl.toString()
     });
-    core.initialization.error = new WebViewFailedToLoadError();
+    raiseFailure('embedded_native_error', {
+      nativeErrorCode: event.code,
+      nativeErrorDescription: event.description,
+      nativeErrorDomain: event.domain,
+      nativeErrorFailedUrl: event.url,
+      nativeErrorIsProvisional: event.isProvisional
+    });
   });
   native.setDebuggingEnabled(_webviewDebuggingEnabled).catch(err => {
     logger.warn('EmbeddedWebView.setDebuggingEnabled failed', err);
@@ -549,44 +1116,21 @@ const setupEmbeddedWebView = ({
     logger.warn('EmbeddedWebView.setUrl failed', err);
   });
   return () => {
+    clearLoadingTimer();
+    clearRecoveryTimer();
     removeVisibilityHandler();
     core.messageTransport.off(handleHostMessage);
+    core.messageTransport.off(handleSdkReady);
     onMessageSub.remove();
     onShouldStartLoadSub.remove();
+    onLoadStartSub.remove();
+    onLoadSub.remove();
+    onLoadEndSub.remove();
     onLoadErrorSub.remove();
+    phaseTimers.dispose();
   };
 };
 
-/******************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-
-function __awaiter(thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-}
-
-typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-};
-
 const setupPasskeyHandler = core => {
   const passkeyRequestChannel = messageTransport.createRequestChannel(core.messageTransport);
   passkeyRequestChannel.handle('passkey_register', _a => __awaiter(void 0, [_a], void 0, function* ({