Add expoUpdatesListenerIntegration that records breadcrumbs for Expo Updates lifecycle events

CHANGELOG.md

@@ -26,6 +26,10 @@
   Sentry.wrapExpoAsset(Asset);
   ```
 - Adds tags with Expo Updates context variables to make them searchable and filterable ([#5788](https://github.com/getsentry/sentry-react-native/pull/5788))
+- Add `expoUpdatesListenerIntegration` that records breadcrumbs for Expo Updates lifecycle events ([#5795](https://github.com/getsentry/sentry-react-native/pull/5795))
+  - Tracks update checks, downloads, errors, rollbacks, and restarts as `expo.updates` breadcrumbs
+  - Enabled by default in Expo apps (requires `expo-updates` to be installed)
+
 - Automatically capture a warning event when Expo Updates performs an emergency launch ([#5794](https://github.com/getsentry/sentry-react-native/pull/5794))
 - Adds environment configuration in the Expo config plugin. This can be set with the `SENTRY_ENVIRONMENT` env variable or in `sentry.options.json` ([#5796](https://github.com/getsentry/sentry-react-native/pull/5796))
   ```json

packages/core/src/js/integrations/default.ts

@@ -19,6 +19,7 @@ import {
   eventOriginIntegration,
   expoConstantsIntegration,
   expoContextIntegration,
+  expoUpdatesListenerIntegration,
   functionToStringIntegration,
   hermesProfilingIntegration,
   httpClientIntegration,
@@ -133,6 +134,7 @@ export function getDefaultIntegrations(options: ReactNativeClientOptions): Integ
 
   integrations.push(expoContextIntegration());
   integrations.push(expoConstantsIntegration());
+  integrations.push(expoUpdatesListenerIntegration());
 
   if (options.spotlight && __DEV__) {
     const sidecarUrl = typeof options.spotlight === 'string' ? options.spotlight : undefined;

packages/core/src/js/integrations/exports.ts

@@ -12,6 +12,7 @@ export { screenshotIntegration } from './screenshot';
 export { viewHierarchyIntegration } from './viewhierarchy';
 export { expoContextIntegration } from './expocontext';
 export { expoConstantsIntegration } from './expoconstants';
+export { expoUpdatesListenerIntegration } from './expoupdateslistener';
 export { spotlightIntegration } from './spotlight';
 export { mobileReplayIntegration } from '../replay/mobilereplay';
 export { feedbackIntegration } from '../feedback/integration';

packages/core/src/js/integrations/expoupdateslistener.ts

@@ -0,0 +1,158 @@
+import { addBreadcrumb, debug, type Integration, type SeverityLevel } from '@sentry/core';
+import type { ReactNativeClient } from '../client';
+import { isExpo, isExpoGo } from '../utils/environment';
+
+const INTEGRATION_NAME = 'ExpoUpdatesListener';
+
+const BREADCRUMB_CATEGORY = 'expo.updates';
+
+/**
+ * Describes the state machine context from `expo-updates`.
+ * We define our own minimal type to avoid a hard dependency on `expo-updates`.
+ */
+interface UpdatesNativeStateMachineContext {
+  isChecking: boolean;
+  isDownloading: boolean;
+  isUpdateAvailable: boolean;
+  isUpdatePending: boolean;
+  isRestarting: boolean;
+  latestManifest?: { id?: string };
+  downloadedManifest?: { id?: string };
+  rollback?: { commitTime: string };
+  checkError?: Error;
+  downloadError?: Error;
+}
+
+interface UpdatesNativeStateChangeEvent {
+  context: UpdatesNativeStateMachineContext;
+}
+
+/**
+ * Tries to load `expo-updates` and retrieve `addUpdatesStateChangeListener`.
+ * Returns `undefined` if `expo-updates` is not installed.
+ */
+function getAddUpdatesStateChangeListener():
+  | ((listener: (event: UpdatesNativeStateChangeEvent) => void) => void)
+  | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires,@typescript-eslint/no-unsafe-member-access
+    const addListener = require('expo-updates').addUpdatesStateChangeListener;
+    if (typeof addListener === 'function') {
+      return addListener as (listener: (event: UpdatesNativeStateChangeEvent) => void) => void;
+    }
+  } catch (_) {
+    // that happens when expo-updates is not installed
+  }
+  return undefined;
+}
+
+interface StateTransition {
+  field: keyof UpdatesNativeStateMachineContext;
+  message: string;
+  level: SeverityLevel;
+  getData?: (ctx: UpdatesNativeStateMachineContext) => Record<string, unknown> | undefined;
+}
+
+const STATE_TRANSITIONS: StateTransition[] = [
+  { field: 'isChecking', message: 'Checking for update', level: 'info' },
+  {
+    field: 'isUpdateAvailable',
+    message: 'Update available',
+    level: 'info',
+    getData: ctx => {
+      const updateId = ctx.latestManifest?.id;
+      return updateId ? { updateId } : undefined;
+    },
+  },
+  { field: 'isDownloading', message: 'Downloading update', level: 'info' },
+  {
+    field: 'isUpdatePending',
+    message: 'Update downloaded',
+    level: 'info',
+    getData: ctx => {
+      const updateId = ctx.downloadedManifest?.id;
+      return updateId ? { updateId } : undefined;
+    },
+  },
+  {
+    field: 'checkError',
+    message: 'Update check failed',
+    level: 'error',
+    getData: ctx => ({
+      error: (ctx.checkError as Error).message || String(ctx.checkError),
+    }),
+  },
+  {
+    field: 'downloadError',
+    message: 'Update download failed',
+    level: 'error',
+    getData: ctx => ({
+      error: (ctx.downloadError as Error).message || String(ctx.downloadError),
+    }),
+  },
+  {
+    field: 'rollback',
+    message: 'Rollback directive received',
+    level: 'warning',
+    getData: ctx => ({
+      commitTime: ctx.rollback!.commitTime,
+    }),
+  },
+  { field: 'isRestarting', message: 'Restarting for update', level: 'info' },
+];
+
+/**
+ * Listens to Expo Updates native state machine changes and records
+ * breadcrumbs for meaningful transitions such as checking for updates,
+ * downloading updates, errors, rollbacks, and restarts.
+ */
+export const expoUpdatesListenerIntegration = (): Integration => {
+  function setup(client: ReactNativeClient): void {
+    client.on('afterInit', () => {
+      if (!isExpo() || isExpoGo()) {
+        return;
+      }
+
+      const addListener = getAddUpdatesStateChangeListener();
+      if (!addListener) {
+        debug.log('[ExpoUpdatesListener] expo-updates is not available, skipping.');
+        return;
+      }
+
+      let previousContext: Partial<UpdatesNativeStateMachineContext> = {};
+
+      addListener((event: UpdatesNativeStateChangeEvent) => {
+        const ctx = event.context;
+        handleStateChange(previousContext, ctx);
+        previousContext = ctx;
+      });
+    });
+  }
+
+  return {
+    name: INTEGRATION_NAME,
+    setup,
+  };
+};
+
+/**
+ * Compares previous and current state machine contexts and emits
+ * breadcrumbs for meaningful transitions (falsy→truthy).
+ *
+ * @internal Exposed for testing purposes
+ */
+export function handleStateChange(
+  previous: Partial<UpdatesNativeStateMachineContext>,
+  current: UpdatesNativeStateMachineContext,
+): void {
+  for (const transition of STATE_TRANSITIONS) {
+    if (!previous[transition.field] && current[transition.field]) {
+      addBreadcrumb({
+        category: BREADCRUMB_CATEGORY,
+        message: transition.message,
+        level: transition.level,
+        data: transition.getData?.(current),
+      });
+    }
+  }
+}