Sentry React Native: Guía de Integración 2026

Tienes una aplicación de React Native funcionando localmente, QA ha dado su visto bueno y la producción está cerca. Luego llega la pregunta obvia: ¿qué pasa cuando se rompe en un dispositivo del usuario?

Sin Sentry, la respuesta suele ser mala. Recibes un ticket de soporte, una captura de pantalla vaga, tal vez un registro de consola de un build de desarrollo que no coincide con la producción. Con Sentry React Native configurado correctamente, obtienes el error, la pila, la versión que lo envió y suficiente contexto para arreglarlo sin adivinar. El problema es que La instalación básica es la parte fácilLa parte dolorosa comienza más tarde: integración nativa, simbolicación, mapas de fuentes, nombres de lanzamiento y mantener todo eso alineado cuando su modelo de entrega incluye actualizaciones en vivo.

La mayoría de las guías se detienen demasiado pronto. Una configuración real debe sobrevivir a CI, compilaciones de App Store, lanzamientos de Android y paquetes de JavaScript que no siempre provienen del binario original.

Índice

• Empezar con Sentry SDK
  • Qué necesitas antes de instalar
  • Ejecutar el asistente y revisar el resultado
• Configuración de proyectos nativos de iOS y Android
  • Qué cambió en iOS
  • Qué cambió en Android
  • Verificaciones de configuración nativa que ahorran tiempo más tarde
• Automatización de lanzamientos y mapas de fuentes
  • ¿Por qué las subidas manuales fallan en la práctica
  • Un proceso de lanzamiento que realmente funciona
  • Un patrón de script de CI práctico
• Capturando datos de rendimiento y eventos personalizados
  • Seguimiento de una pantalla lenta en lugar de adivinar
  • Agregar contexto útil a errores
• Verificando y resolviendo problemas en tu integración
  • Activar eventos de prueba de manera segura
  • ¿Qué verificar en la interfaz de usuario de Sentry?
  • Problemas de depuración comunes de Sentry React Native
• Integrar con flujos de actualización en vivo como Capgo
  • Coincidir identificadores de lanzamiento con paquetes en vivo

Empezando con el SDK de Sentry

La forma más rápida de incorporar Sentry React Native en una nueva aplicación sigue siendo el asistente de instalación. Maneja la mayoría de la configuración repetitiva y te lleva a una base de trabajo funcional rápidamente. Eso importa, porque hacer el primer instalación manualmente suele llevar a pequeñas incompatibilidades que no notarás hasta el primer crash en producción.

¿Qué necesitas antes de instalar

Necesitas un entorno de desarrollo de React Native normal primero. Node, un administrador de paquetes, herramientas de plataforma para iOS y Android, y Watchman en macOS si ya forma parte de tu flujo de trabajo. También necesitas una cuenta de Sentry y un proyecto creado para React Native.

Si todavía estás evaluando si React Native es la elección operativa correcta para tu equipo, este Guía de React Native para empresas proporciona contexto útil no publicitario sobre las compensaciones de plataforma, personal y expectativas de mantenimiento. Es recomendable leerlo antes de comprometer tu proceso de monitoreo y lanzamiento alrededor de un código compartido.

Instala el SDK con el asistente desde la raíz del proyecto:

npx @sentry/wizard@latest -i reactNative

El asistente te hace algunas preguntas que los desarrolladores a menudo pasan demasiado rápido:

• Selección de proyectoElige el proyecto de Sentry real que planeas usar en producción, no un sandbox temporal que olvidarás actualizar más tarde.
• Cambios nativos. Diga sí. La captura de errores solo en JavaScript no es suficiente para aplicaciones móviles.
• Características opcionales. Activa solo lo que sabes que usarás, pero no habilites todo de manera ciega el primer día si tu equipo no revisará los datos resultantes.

Ejecutar el asistente y revisar el resultado

Después de que el asistente termine, inspecciona los cambios en lugar de confiar en ellos sin revisión. Deberías ver un paquete de Sentry en package.json, cambios nativos bajo ios y androidun bloque de inicialización en tu archivo de entrada de la aplicación.

Una inicialización típica se ve así:

import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'YOUR_DSN',
});

El DSN indica al SDK dónde enviar eventos. Trátalo como configuración, no como un almacén de secretos que nunca debe estar visible. No es lo mismo que un token de autenticación. Sin embargo, mantén tu configuración de entorno limpia y consistente para que tu aplicación apunte al proyecto de Sentry correcto en cada entorno.

A un patrón práctico es cargar el DSN desde la configuración específica del entorno y inicializar Sentry antes de que el resto de la arbol de tu aplicación monte. Si también estás trabajando en la pulido de inicio, esta guía sobre la configuración de pantalla de inicio de React Native es útil porque el orden de inicio de la aplicación a menudo se cruza con dónde equipos colocan la inicialización de Sentry. Configuración de pantalla de inicio de React Native is useful because startup code order often intersects with where teams place Sentry initialization.

Regla práctica: Inicializa Sentry lo antes posible en el inicio de la aplicación. Si esperas hasta después de la navegación, la hidratación de autenticación o la configuración remota, te perderás los errores de inicio.

En este momento, no busques la perfección. El objetivo inmediato es simple: lanza la aplicación, desencadena una excepción de JavaScript más adelante en el artículo y confirma que los eventos llegan a Sentry. Una vez que eso funciona, las capas nativas y de lanzamiento se vuelven mucho más fáciles de razonar.

Configuración de proyectos nativos de iOS y Android

At this stage, many React Native teams get a false sense of completion. The JavaScript SDK is installed, events show up, and everyone assumes crash reporting is done. It isn’t. If native integration is off, some of the crashes you care about most will never reach Sentry in a usable form.

¿Qué cambió en iOS?

Abre el proyecto de iOS y revisa qué cambió el asistente. En una aplicación React Native bare, eso significa normalmente actualizaciones alrededor del inicio de la aplicación y las fases de compilación. Estás buscando hooks de inicialización de Sentry y pasos de carga relacionados con tu proceso de compilación.

En Xcode, revisa estos lugares:

• App delegate startup code. La aplicación necesita la inicialización nativa de Sentry temprano en el lanzamiento.
• Fases de compilación. Busque cualquier script de carga de Sentry relacionado con símbolos de depuración o manejo de mapas de fuentes.
• Configuración de compilación y comportamiento de archivo. Los archivos de símbolos deben generarse y estar disponibles durante las compilaciones de archivo.

Si su aplicación utiliza AppDelegate.mm, la inicialización a menudo se encuentra cerca de la inicialización de la puente de React Native. El contenido del archivo puede variar según la versión de React Native, el modelo y si está utilizando la nueva arquitectura, por lo que no copie fragmentos de código de repositorios aleatorios a menos que coincidan con la forma de su proyecto.

Lo que importa es la intención: los errores nativos de iOS necesitan datos de símbolos, y la aplicación debe iniciar Sentry antes de que el error pueda observarse de manera fiable.

Si los errores de iOS aparecen en Sentry con marcos nativos no legibles, el problema suele no ser "Sentry está roto". Es la carga de símbolos o la correspondencia de la versión.

¿Qué cambió en Android?

Android suele agregar cambios en los archivos Gradle y a veces la configuración a nivel de manifiesto. Revisa android/build.gradle, android/app/build.gradle, y cualquier configuración o enrutamiento relacionado con Sentry.

Cosas a verificar:

1. Se aplica el plugin de Sentry Gradle para que los artefactos de la versión puedan ser procesados durante el tiempo de compilación.
2. El manejo de variantes es correcto si se utilizan sabores de producto o múltiples tipos de compilación.
3. Se tienen en cuenta los resultados de ProGuard o R8 si las compilaciones de liberación reducen o desfiguran code.

Un error común en Android es suponer que una ejecución de depuración local exitosa prueba que la configuración de la versión está correcta. No lo está. La ruta de la versión es diferente, especialmente una vez que se introducen la minimización y la firma de CI. Si su equipo mantiene compilaciones de depuración, pruebas, QA y tienda separadas, esta descomposición de tipos de compilación móviles es una referencia útil para mantener el comportamiento de monitoreo alineado con cada variante de compilación.

Verificaciones de configuración nativa que ahorran tiempo más adelante

No se detenga en ‘el asistente modificó archivos.’ Verifique el comportamiento directamente.

Use this checklist:

• Archivar una compilación de iOS localmente y confirmar que la compilación no falla durante el procesamiento de símbolos.
• Crear una compilación de lanzamiento de Android y inspeccionar los registros de CI para tareas relacionadas con Sentry.
• Verificar la asignación del nombre de paquete e identificador de paquete en Sentry si administra múltiples aplicaciones bajo una organización.
• Confirmar las convenciones de nombres de lanzamiento ahora, antes de que CI comience subiendo artefactos con nombres inconsistentes.

Aquí está lo que generalmente no funciona bien:

La mejor configuración es aburrida. Los hooks de arranque nativos están en su lugar, los scripts de compilación se ejecutan cada vez y el nombre de la versión es determinístico en iOS, Android y paquetes de JavaScript.

Automatizar versiones y mapas de fuentes

Si hay un lugar donde las configuraciones de Sentry React Native se desmoronan, es aquí. Los equipos instalan el SDK, ven eventos y postergan la automatización de versiones. Luego llega la primera cuestión seria de producción y el seguimiento de pila está minimizado, la versión falta o el subir el mapa de fuentes pertenecía a un paquete diferente.

Subir mapas de fuentes manualmente parece aceptable cuando se envían con poca frecuencia. En la práctica, fallan porque los humanos son malos en la contabilidad de versiones repetitiva.

Por qué los subidos manuales fallan en la práctica

Los modos de falla son predecibles:

• Alguien olvida subir los mapas después de una actualización nocturna.
• Los archivos subidos pertenecen a un commit diferente que el paquete binario o de actualización OTA que utilizan los usuarios.
• El nombre de la versión cambia ligeramente entre los pasos de iOS, Android y CI.
• Se produce una reconstrucción después de subir los mapas y invalida lo que Sentry debería estar buscando.

Por eso no recomiendo un enfoque de ‘documentar los pasos en Notion’.

Un diagrama de flujo de siete pasos que ilustra el proceso automatizado de gestión de versiones de Sentry y mapas de origen para React Native.

Un proceso de versión que realmente resiste la prueba del tiempo. Un conjunto de configuración confiable tiene algunas propiedades:

• Los IDs de lanzamiento se generan una vez y se reutilizan en todas partes.
• Los pasos de construcción, empaquetado y carga ocurren en la misma canalización.
• Los mapas de origen se cargan desde CI, no desde una laptop de desarrollador.
• La aplicación inicia Sentry con la misma cadena de lanzamiento que CI utilizó durante la carga.

El último punto es más importante de lo que comúnmente se espera. No solo necesitas mapas de origen en Sentry. Necesitas los mapas de origen correctos adjuntos al identificador de lanzamiento exacto emitido por la aplicación en tiempo de ejecución.

Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de construcción y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions El correcto funcionamiento de la aplicación depende de la correcta configuración de los mapas de origen en Sentry.

A un script de CI práctico

Utiliza un script como este en CI y alimenta valores de tu entorno de pipeline:

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

Debes adaptar el comando de paquete para Android, y muchas equipos dividen trabajos específicos de plataforma en lugar de forzar a un script a realizar ambos. Eso está bien. Lo que importa es la consistencia.

La disciplina de lanzamiento supera la programación ingeniosa. Elige una convención de nombres, inyecta en la aplicación durante el tiempo de compilación y nunca permitas subidas ad hoc locales que compitan con CI.

Para React Native, prefiero almacenar la cadena de lanzamiento en una ubicación de configuración generada por la compilación y leerla durante Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

El beneficio es simple. Cuando llega un evento, Sentry puede mapear el frame minimizado hacia el code que enviaste, no hacia el code que crees que enviaste.

Captura de datos de rendimiento y eventos personalizados

Los errores te dicen qué se rompió. La trazabilidad de rendimiento te dice qué sintieron los usuarios antes de darse por vencidos.

Un informe común suena así: “La interfaz de usuario es lenta.” Eso no es suficiente para depurar. Lenta en dónde? Durante la navegación? Durante la carga de datos? Mientras se renderiza un gráfico pesado?

Un desarrollador de software codificando en una laptop con gráficos de visualización de datos mostrados en un monitor de fondo.

Comience habilitando la trazabilidad de rendimiento en su inicialización. La estrategia de muestreo exacta depende de su entorno y tolerancia de volumen, pero la estructura se parece a esto:

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Si utiliza React Navigation, conecte la integración para que las transiciones de pantalla produzcan datos de trazabilidad. Luego reproduzca el queja en un dispositivo físico, no solo en un simulador. Los simuladores ocultan el tipo de lentitud que los usuarios notan.

Un ejemplo práctico de panel de control:

1. Un usuario abre el panel de control principal después de iniciar sesión.
2. La navegación se completa, pero el contenido aparece tarde.
3. La traza muestra que la transacción de pantalla es larga.
4. Las spans de hijo revelan un pedido API y un camino de renderizado costoso.
5. Optimiza el camino de renderizado, envíe nuevamente y compare la nueva forma de la traza.

Es mejor que argumentar desde la intuición.

Para equipos que piensan ampliamente sobre patrones de monitoreo de aplicaciones híbridas o de webview, este escrito sobre monitoreo de rendimiento en proyectos Capacitor es digno de una revisión rápida porque la mentalidad operativa es similar aunque la pila difiera.

Agregar contexto útil a errores

Los datos de rendimiento se vuelven más útiles cuando los eventos contienen contexto empresarial. No metadatos de vanidad. Solo lo suficiente para responder quién se vio afectado, qué pantalla estaban viendo y qué sucedió justo antes de la falla.

Usa estos herramientas con intención:

• Contexto del usuario con Sentry.setUser() para que el soporte pueda correlacionar informes con una cuenta afectada sin tener que buscar en el adivinamiento.
• Breadcrumbs para acciones como pulsar enviar, abrir un modal o iniciar un sincronización.
• Etiquetas personalizadas para dimensiones como tipo de plan, estado de bandera de características o API región.
• Excepciones capturadas con contexto adicional cuando atrapas y rellanzas o superficies fallas controladas.

Example:

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

La diferencia entre “el usuario dice que la aplicación se congeló” y “la aplicación falló después de abrir el panel de control, iniciar la sincronización y volver a intentar una solicitud caducada” suele ser un rastro de navegación.

Cuando la instrumentación personalizada falla, lo hace generalmente por ser demasiado ruidosa. No capture cada pulsación de botón en la aplicación para siempre. Captura límites, transiciones de estado y operaciones que importan al depurar. Un contexto suficiente para explicar el evento. No demasiado para ahogarlo.

Verificar y depurar su integración

Debería verificar Sentry antes de enviar la aplicación, después de cambios en la pipeline de compilación y después de SDK actualizaciones. “Funcionó durante meses” no es un test significativo.

La forma más limpia es provocar fallas controladas tanto para JavaScript como para rutas nativas, luego inspeccionar cómo llegan a Sentry.

Producir eventos de prueba de manera segura

Para un error de JavaScript, agrega un botón temporal en una pantalla no de producción:

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

Para una excepción capturada que no hará que la aplicación se caiga:

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

La prueba de fallas nativas debe hacerse con cuidado y solo en compilaciones de desarrollo o de QA controladas. Los métodos de ayuda exactos disponibles pueden variar según la versión de SDK y la configuración de plataforma, por lo que prefiero utilizar la utilidad de prueba de fallas nativa documentada de SDK cuando esté presente en lugar de inventar mi propio camino de falla.

Qué verificar en la interfaz de usuario de Sentry

When el evento aparece, inspecciona más que el título.

Ver estos campos:

• Plataforma y mecanismo. Esto ayuda a distinguir excepciones de JS de crash nativos.
• Versión y dist. Si están en blanco o están mal, los mapas de fuentes y la simbología se desviarán.
• Marcas de pila. Deben aparecer ubicaciones de fuentes legibles para los mapas de JavaScript cargados correctamente.
• Pan y etiquetas. Confirma que tu contexto personalizado llegó.
• Entorno. Asegúrate de que los eventos de desarrollo y producción no se mezclen en un flujo.

If un evento nativo llega pero tiene una mala simbolicación, no sigas ajustando la aplicación code. Eso suele ser un problema de artefacto de compilación.

Trabajos de depuración comunes de Sentry React Native

Una costumbre final que vale la pena es mantener una lista de comprobación de pruebas de humo de monitoreo muy pequeña en tu proceso de liberación. Desencadé una evento JS en staging, confirma los valores de liberación y verifica las ubicaciones de origen antes de promover una compilación

Integrar con flujos de trabajo de actualizaciones en vivo como Capgo

Las actualizaciones en vivo cambian el modelo de liberación. El binario en la tienda puede permanecer igual mientras el paquete de JavaScript cambia debajo de él. Si Sentry sigue pensando solo en términos de la versión de la aplicación original, las pila de trazas se vuelven engañosas rápidamente

La solución es hacer que la identidad de liberación de Sentry siga el paquete de JavaScript en vivo no solo el binario nativoCoincidir identificadores de liberación con paquetes de JavaScript en vivo

Para flujos de trabajo de actualizaciones en vivo, trate

y release contexto: Página/área: Sitio web de marketing de Capgo. Rol: Etiqueta de IU corta o elemento de navegación. Visto en: página trust.astro. Clave de mensaje `y` (Y) dist como identificadores de tiempo de ejecución vinculados al paquete de JavaScript entregado. La versión de la aplicación nativa sigue siendo importante, pero ya no es suficiente una vez que los paquetes pueden cambiar independientemente

Un patrón práctico se parece a esto

• Utilice la versión de la aplicación nativa como parte del nombre de la versión base.
• Anexe la versión de actualización en vivo o el identificador del paquete.
• Utilice dist para la diferenciación específica de canal o construcción cuando se adapte a su modelo.
• Suba los mapas de fuentes para cada paquete en vivo bajo ese identificador de versión exacta.

Por ejemplo, si su aplicación carga metadatos de actualización al inicio, inicialice Sentry con valores derivados del paquete actualmente activo, no solo de la configuración de construcción estática.

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

De esta manera, cuando un usuario golpee un error en un paquete actualizado en caliente, Sentry resuelve marcos contra el mapa de fuentes para esa actualización en caliente en lugar del paquete de almacenamiento de la tienda más antiguo.

Esto importa con cualquier flujo de trabajo de actualización OTA. Si desea una buena introducción a los piezas en movimiento detrás de ese modelo de entrega, esta explicación de ¿Cómo funcionan las actualizaciones en vivo en las aplicaciones Capacitor es una referencia sólida.

Aquí está el tipo de visión operativa que los equipos buscan cuando combinan metadatos de actualización con seguimiento de versiones:

El principal error a evitar es reutilizar una cadena de liberación estática para cada actualización de post-almacenamiento. Si varios paquetes comparten la misma liberación Sentry, el depurado se convierte en adivinanza de nuevo.

Si su equipo envía correcciones fuera de los ciclos de revisión de la tienda de aplicaciones Capgo es valioso evaluar. Le da a los equipos Capacitor una forma estructurada de entregar actualizaciones en vivo, dirigir canales, controlar los lanzamientos y recuperarse rápidamente de las liberaciones malas. Pair eso con la nominación disciplinada de liberaciones Sentry y subidas de mapas de origen, y obtendrá un flujo de trabajo donde los errores aún apuntan a los usuarios exactos code que están ejecutando.