feat(core): Add Sentry.appLoaded() API to signal app start end

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Features
 
+- Add `Sentry.appLoaded()` API to explicitly signal app start end ([#5940](https://github.com/getsentry/sentry-react-native/pull/5940))
 - Add `frames.delay` span data from native SDKs to app start, TTID/TTFD, and JS API spans ([#5907](https://github.com/getsentry/sentry-react-native/pull/5907))
 - Rename `FeedbackWidget` to `FeedbackForm` and `showFeedbackWidget` to `showFeedbackForm` ([#5931](https://github.com/getsentry/sentry-react-native/pull/5931))
   - The old names are deprecated but still work

packages/core/src/js/index.ts

@@ -73,7 +73,7 @@ export { SDK_NAME, SDK_VERSION } from './version';
 export type { ReactNativeOptions, NativeLogEntry } from './options';
 export { ReactNativeClient } from './client';
 
-export { init, wrap, nativeCrash, flush, close, withScope, crashedLastRun } from './sdk';
+export { init, wrap, nativeCrash, flush, close, withScope, crashedLastRun, appLoaded } from './sdk';
 export { TouchEventBoundary, withTouchEventBoundary } from './touchevents';
 
 export {

packages/core/src/js/sdk.tsx

@@ -25,6 +25,7 @@ import { shouldEnableNativeNagger } from './options';
 import { enableSyncToNative } from './scopeSync';
 import { TouchEventBoundary } from './touchevents';
 import { ReactNativeProfiler } from './tracing';
+import { _appLoaded } from './tracing/integrations/appStart';
 import { useEncodePolyfill } from './transports/encodePolyfill';
 import { DEFAULT_BUFFER_SIZE, makeNativeTransportFactory } from './transports/native';
 import { getDefaultEnvironment, isExpoGo, isRunningInMetroDevServer, isWeb } from './utils/environment';
@@ -220,6 +221,31 @@ export function nativeCrash(): void {
   NATIVE.nativeCrash();
 }
 
+/**
+ * Signals that the application has finished loading and is ready for user interaction.
+ *
+ * Call this when your app is truly ready — after async initialization, data loading,
+ * splash screen dismissal, auth session restore, etc. This marks the end of the app start span,
+ * giving you a more accurate measurement of perceived startup time.
+ *
+ * If not called, the SDK falls back to the root component mount time (via `Sentry.wrap()`)
+ * or JS bundle execution start.
+ *
+ * @experimental This API is subject to change in future versions.
+ *
+ * @example
+ * ```ts
+ * await loadRemoteConfig();
+ * await restoreSession();
+ * SplashScreen.hide();
+ * Sentry.appLoaded();
+ * ```
+ */
+export function appLoaded(): void {
+  // oxlint-disable-next-line typescript-eslint(no-floating-promises)
+  _appLoaded();
+}
+
 /**
  * Flushes all pending events in the queue to disk.
  * Use this before applying any realtime updates such as code-push or expo updates.

packages/core/src/js/tracing/integrations/appStart.ts

@@ -37,6 +37,7 @@ const INTEGRATION_NAME = 'AppStart';
 
 export type AppStartIntegration = Integration & {
   captureStandaloneAppStart: () => Promise<void>;
+  resetAppStartDataFlushed: () => void;
 };
 
 /**
@@ -59,24 +60,78 @@ interface AppStartEndData {
 
 let appStartEndData: AppStartEndData | undefined = undefined;
 let isRecordedAppStartEndTimestampMsManual = false;
+let isAppLoadedManuallyInvoked = false;
 
 let rootComponentCreationTimestampMs: number | undefined = undefined;
 let isRootComponentCreationTimestampMsManual = false;
 
 /**
  * Records the application start end.
  * Used automatically by `Sentry.wrap` and `Sentry.ReactNativeProfiler`.
+ *
+ * @deprecated Use {@link appLoaded} from the public SDK API instead (`Sentry.appLoaded()`).
  */
 export function captureAppStart(): Promise<void> {
   return _captureAppStart({ isManual: true });
 }
 
+/**
+ * Signals that the app has finished loading and is ready for user interaction.
+ * Called internally by `appLoaded()` from the public SDK API.
+ *
+ * @private
+ */
+export async function _appLoaded(): Promise<void> {
+  if (isAppLoadedManuallyInvoked) {
+    debug.warn('[AppStart] appLoaded() was already called. Subsequent calls are ignored.');
+    return;
+  }
+
+  const client = getClient();
+  if (!client) {
+    debug.warn('[AppStart] appLoaded() was called before Sentry.init(). App start end will not be recorded.');
+    return;
+  }
+
+  isAppLoadedManuallyInvoked = true;
+
+  const timestampMs = timestampInSeconds() * 1000;
+
+  // If auto-capture already ran (ReactNativeProfiler.componentDidMount), overwrite the timestamp.
+  // The transaction hasn't been sent yet in non-standalone mode so this is safe.
+  if (appStartEndData) {
+    debug.log('[AppStart] appLoaded() overwriting auto-detected app start end timestamp.');
+    appStartEndData.timestampMs = timestampMs;
+    appStartEndData.endFrames = null;
+  } else {
+    _setAppStartEndData({ timestampMs, endFrames: null });
+  }
+  isRecordedAppStartEndTimestampMsManual = true;
+
+  await fetchAndUpdateEndFrames();
+
+  const integration = client.getIntegrationByName<AppStartIntegration>(INTEGRATION_NAME);
+  if (integration) {
+    // In standalone mode, auto-capture may have already flushed the transaction.
+    // Reset the flag so captureStandaloneAppStart can re-send with the manual timestamp.
+    integration.resetAppStartDataFlushed();
+    await integration.captureStandaloneAppStart();
+  }
+}
+
 /**
  * For internal use only.
  *
  * @private
  */
 export async function _captureAppStart({ isManual }: { isManual: boolean }): Promise<void> {
+  // If appLoaded() was already called manually, skip the auto-capture to avoid
+  // overwriting the manual end timestamp (race B: appLoaded before componentDidMount).
+  if (!isManual && isAppLoadedManuallyInvoked) {
+    debug.log('[AppStart] Skipping auto app start capture because appLoaded() was already called.');
+    return;
+  }
+
   const client = getClient();
   if (!client) {
     debug.warn('[AppStart] Could not capture App Start, missing client.');
@@ -94,6 +149,14 @@ export async function _captureAppStart({ isManual }: { isManual: boolean }): Pro
     endFrames: null,
   });
 
+  await fetchAndUpdateEndFrames();
+  await client.getIntegrationByName<AppStartIntegration>(INTEGRATION_NAME)?.captureStandaloneAppStart();
+}
+
+/**
+ * Fetches native frames data and attaches it to the current app start end data.
+ */
+async function fetchAndUpdateEndFrames(): Promise<void> {
   if (NATIVE.enableNative) {
     try {
       const endFrames = await NATIVE.fetchNativeFrames();
@@ -103,8 +166,6 @@ export async function _captureAppStart({ isManual }: { isManual: boolean }): Pro
       debug.log('[AppStart] Failed to capture end frames for app start.', error);
     }
   }
-
-  await client.getIntegrationByName<AppStartIntegration>(INTEGRATION_NAME)?.captureStandaloneAppStart();
 }
 
 /**
@@ -160,6 +221,17 @@ export function _clearRootComponentCreationTimestampMs(): void {
   rootComponentCreationTimestampMs = undefined;
 }
 
+/**
+ * For testing purposes only.
+ *
+ * @private
+ */
+export function _clearAppStartEndData(): void {
+  appStartEndData = undefined;
+  isRecordedAppStartEndTimestampMsManual = false;
+  isAppLoadedManuallyInvoked = false;
+}
+
 /**
  * Attaches frame data to a span's data object.
  */
@@ -230,6 +302,7 @@ export const appStartIntegration = ({
         appStartDataFlushed = false;
         firstStartedActiveRootSpanId = undefined;
         firstStartedActiveRootSpan = undefined;
+        isAppLoadedManuallyInvoked = false;
       } else {
         debug.log(
           '[AppStartIntegration] Waiting for initial app start was flush, before updating based on runApplication call.',
@@ -540,12 +613,17 @@ export const appStartIntegration = ({
     );
   }
 
+  const resetAppStartDataFlushed = (): void => {
+    appStartDataFlushed = false;
+  };
+
   return {
     name: INTEGRATION_NAME,
     setup,
     afterAllSetup,
     processEvent,
     captureStandaloneAppStart,
+    resetAppStartDataFlushed,
     setFirstStartedActiveRootSpanId,
   } as AppStartIntegration;
 };