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

Adds a public `Sentry.appLoaded()` function that users can call to
explicitly signal when their app is fully ready for user interaction.
This provides a more accurate app start end timestamp for apps that
do significant async work after the root component mounts (e.g.
remote config fetching, session restore, splash screen dismissal).

When appLoaded() is called it:
- Records the current timestamp as the manual app start end
- Fetches native frames for frame data attachment
- Triggers standalone app start capture when in standalone mode

Priority / race condition handling:
- appLoaded() before ReactNativeProfiler.componentDidMount: the auto
  capture in _captureAppStart({ isManual: false }) is skipped entirely
- appLoaded() after componentDidMount: the existing appStartEndData
  timestamp is overwritten with the manual (later) value; since the
  app start spans are attached to the first navigation transaction
  (which hasn't been flushed yet), the correct timestamp is used

Existing behaviour is unchanged when appLoaded() is not called.
The three-tier fallback (wrap -> bundle start -> warn) still applies.

Adds _appLoaded() internal function, _clearAppStartEndData() testing
helper, and five new unit tests covering: manual timestamp, duplicate
call guard, post-auto-capture override, pre-auto-capture guard, and
no-op before Sentry.init().

Author: alwx

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add `Sentry.appLoaded()` API to explicitly signal app start end ([#XXXX](https://github.com/getsentry/sentry-react-native/pull/XXXX))
+
 ### Fixes
 
 - Fix iOS crash (EXC_BAD_ACCESS) in time-to-initial-display when navigating between screens ([#5887](https://github.com/getsentry/sentry-react-native/pull/5887))

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,29 @@ 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.
+ *
+ * @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

@@ -59,6 +59,7 @@ interface AppStartEndData {
 
 let appStartEndData: AppStartEndData | undefined = undefined;
 let isRecordedAppStartEndTimestampMsManual = false;
+let isAppLoadedManuallyInvoked = false;
 
 let rootComponentCreationTimestampMs: number | undefined = undefined;
 let isRootComponentCreationTimestampMsManual = false;
@@ -71,12 +72,64 @@ 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;
+  }
+  isAppLoadedManuallyInvoked = true;
+
+  const client = getClient();
+  if (!client) {
+    debug.warn('[AppStart] appLoaded() was called before Sentry.init(). App start end will not be recorded.');
+    return;
+  }
+
+  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;
+
+  if (NATIVE.enableNative) {
+    try {
+      const endFrames = await NATIVE.fetchNativeFrames();
+      debug.log('[AppStart] Captured end frames for app start.', endFrames);
+      _updateAppStartEndFrames(endFrames);
+    } catch (error) {
+      debug.log('[AppStart] Failed to capture end frames for app start.', error);
+    }
+  }
+
+  await client.getIntegrationByName<AppStartIntegration>(INTEGRATION_NAME)?.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.');
@@ -160,6 +213,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.
  */

packages/core/test/tracing/integrations/appStart.test.ts

@@ -1,6 +1,7 @@
 import type { ErrorEvent, Event, Integration, SpanJSON, TransactionEvent } from '@sentry/core';
 
 import {
+  debug,
   getCurrentScope,
   getGlobalScope,
   getIsolationScope,
@@ -24,7 +25,9 @@ import {
   UI_LOAD,
 } from '../../../src/js/tracing';
 import {
+  _appLoaded,
   _captureAppStart,
+  _clearAppStartEndData,
   _clearRootComponentCreationTimestampMs,
   _setAppStartEndData,
   _setRootComponentCreationTimestampMs,
@@ -1024,6 +1027,134 @@ describe('App Start Integration', () => {
   });
 });
 
+describe('appLoaded() API', () => {
+  let client: TestClient;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    _clearAppStartEndData();
+    _clearRootComponentCreationTimestampMs();
+    mockReactNativeBundleExecutionStartTimestamp();
+    client = new TestClient({
+      ...getDefaultTestClientOptions(),
+      enableAppStartTracking: true,
+      tracesSampleRate: 1.0,
+    });
+    setCurrentClient(client);
+    client.init();
+  });
+
+  afterEach(() => {
+    clearReactNativeBundleExecutionStartTimestamp();
+    _clearAppStartEndData();
+    _clearRootComponentCreationTimestampMs();
+  });
+
+  function makeIntegration(): AppStartIntegrationTest {
+    const integration = appStartIntegration({ standalone: false }) as AppStartIntegrationTest;
+    integration.setup(client);
+    integration.afterAllSetup(client);
+    return integration;
+  }
+
+  it('sets the app start end timestamp and marks it as manual', async () => {
+    const appLoadedTimeSeconds = Date.now() / 1000;
+    mockFunction(timestampInSeconds).mockReturnValue(appLoadedTimeSeconds);
+
+    await _appLoaded();
+
+    const appStartTimeMilliseconds = appLoadedTimeSeconds * 1000 - 3000;
+    mockFunction(NATIVE.fetchNativeAppStart).mockResolvedValue({
+      type: 'cold' as const,
+      app_start_timestamp_ms: appStartTimeMilliseconds,
+      has_fetched: false,
+      spans: [],
+    });
+
+    const integration = makeIntegration();
+    integration.setFirstStartedActiveRootSpanId('test-span-id');
+
+    const event: TransactionEvent = {
+      type: 'transaction',
+      start_timestamp: Date.now() / 1000,
+      timestamp: Date.now() / 1000 + 1,
+      contexts: { trace: { span_id: 'test-span-id', trace_id: 'trace123' } },
+    };
+
+    const processed = (await integration.processEvent(event, {}, client)) as TransactionEvent;
+    const appStartSpan = processed.spans?.find(s => s.op === APP_START_COLD_OP);
+
+    expect(appStartSpan).toBeDefined();
+    expect(appStartSpan?.timestamp).toBeCloseTo(appLoadedTimeSeconds, 1);
+    expect(appStartSpan?.origin).toBe(SPAN_ORIGIN_MANUAL_APP_START);
+  });
+
+  it('ignores subsequent calls after first invocation', async () => {
+    const warnSpy = jest.spyOn(debug, 'warn');
+
+    await _appLoaded();
+    await _appLoaded();
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('already called'));
+  });
+
+  it('overrides auto-detected timestamp when called after _captureAppStart', async () => {
+    const now = Date.now();
+    const autoTimeSeconds = now / 1000;
+    const manualTimeSeconds = now / 1000 + 0.5;
+    const appStartTimeMilliseconds = now - 3000;
+
+    mockFunction(timestampInSeconds).mockReturnValueOnce(autoTimeSeconds);
+    await _captureAppStart({ isManual: false });
+
+    mockFunction(timestampInSeconds).mockReturnValueOnce(manualTimeSeconds);
+    await _appLoaded();
+
+    mockFunction(NATIVE.fetchNativeAppStart).mockResolvedValue({
+      type: 'cold' as const,
+      app_start_timestamp_ms: appStartTimeMilliseconds,
+      has_fetched: false,
+      spans: [],
+    });
+
+    const integration = makeIntegration();
+    integration.setFirstStartedActiveRootSpanId('span-override');
+
+    const event: TransactionEvent = {
+      type: 'transaction',
+      start_timestamp: now / 1000,
+      timestamp: now / 1000 + 2,
+      contexts: { trace: { span_id: 'span-override', trace_id: 'trace' } },
+    };
+
+    const processed = (await integration.processEvent(event, {}, client)) as TransactionEvent;
+    const appStartSpan = processed.spans?.find(s => s.op === APP_START_COLD_OP);
+    expect(appStartSpan?.timestamp).toBeCloseTo(manualTimeSeconds, 1);
+  });
+
+  it('prevents auto-capture from overriding when called before _captureAppStart', async () => {
+    await _appLoaded();
+
+    const logSpy = jest.spyOn(debug, 'log');
+    await _captureAppStart({ isManual: false });
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Skipping auto app start capture'));
+  });
+
+  it('warns and is a no-op when called before Sentry.init', async () => {
+    const warnSpy = jest.spyOn(debug, 'warn');
+    getCurrentScope().setClient(undefined);
+    getGlobalScope().setClient(undefined);
+    getIsolationScope().setClient(undefined);
+
+    await _appLoaded();
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('before Sentry.init'));
+
+    setCurrentClient(client);
+  });
+});
+
 describe('Frame Data Integration', () => {
   it('attaches frame data to standalone cold app start span', async () => {
     const mockEndFrames = {