Guía de Integración de Sentry React Native: 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. Obtienes un ticket de soporte, una captura de pantalla vaga, quizás 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, el stack, la versión que lo envió y suficiente contexto para solucionarlo sin adivinar. El catch es que La instalación básica es la parte fácil. Los partes dolorosas vienen después: integración nativa, simbolicación, mapas de origen, 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 tiene que 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
  • Lo que necesitas antes de instalar
  • Ejecutar el asistente y revisar el resultado
• Configurando proyectos nativos de iOS y Android
  • ¿Qué cambió en iOS?
  • ¿Qué cambió en Android?
  • Comprobaciones de configuración nativa que ahorrarán tiempo más tarde
• Automatizar lanzamientos y mapas de origen
  • Why los 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 depurando su 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
• Integrando con flujos de trabajo de actualización en vivo como Capgo
  • Coincidir identificadores de lanzamiento con paquetes en vivo

Empezando con Sentry SDK

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 ofrece contexto no publicitario útil sobre las compensaciones de plataforma, personal y expectativas de mantenimiento. Es recomendable leer 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 suelen hacer clic 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 con 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 android, y un bloque de inicialización en el archivo de entrada de tu aplicación.

Un inicio típico se ve así:

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

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

El DSN indica a 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 arboleda de tu aplicación se monte. Si también estás trabajando en la pulido de inicio, esta guía sobre la configuración de la 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.

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: lanzar la aplicación, desencadenar una excepción de JavaScript más adelante en el artículo y confirmar que los eventos llegan a Sentry. Una vez que esto 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

En este momento, muchos equipos de React Native obtienen una falsa sensación de completitud. El JavaScript está instalado, los eventos aparecen y todos asumen que el informe de errores de la aplicación está completo. No lo está. Si la integración nativa está desactivada, algunos de los errores que más te importan nunca llegarán a Sentry en una forma utilizable.

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.

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

En Xcode, revisa estos lugares:

Inicio de delegado de aplicación __CAPGO_KEEP_0__

• App delegate startup code. La aplicación necesita la inicialización nativa de Sentry temprano en la puesta en marcha.
• 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 se está utilizando la nueva arquitectura, por lo que no copie snippets de repositorios aleatorios a menos que coincidan con la forma de su proyecto.

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

Si los errores de iOS aparecen en Sentry con marcos nativos no leídos, el problema usualmente no es “Sentry está roto.” Es la carga de símbolos o la correspondencia de la versión de lanzamiento.

¿Qué cambió en Android

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

Cosas a verificar:

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

Un error común en Android es suponer que una ejecución de depuración local exitosa prueba que la configuración de liberación está correcta. No lo está. La ruta de liberación es diferente, especialmente una vez que se introducen la minificació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 mago modificó archivos.” Verifique el comportamiento directamente.

Use this checklist:

• Archiva una compilación de iOS localmente y confirma que la compilación no falla durante el procesamiento de símbolos.
• Crear una compilación de lanzamiento de Android y inspecciona los registros de CI para tareas relacionadas con Sentry.
• Verifica la asignación del nombre de paquete y el identificador de conjunto de recursos en Sentry si administras múltiples aplicaciones bajo una organización. Confirma las convenciones de nombres de lanzamiento ahora
• , antes de que CI comience subiendo artefactos con nombres inconsistentes.Aquí está lo que no funciona bien generalmente:

Enfoque

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 JavaScript bundles.

Automatizar Lanzamientos 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 lanzamientos. Luego llega el primer problema serio en producción y la pila de seguimiento está minificada, la versión falta o el archivo de mapas de fuentes pertenecía a un paquete diferente.

Los subidas de mapas de fuentes manuales parecen aceptables 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é las subidas manuales fallan en la práctica

Los modos de falla son predecibles:

• Alguien olvida subir mapas después de una actualización nocturna.
• Los archivos subidos pertenecen a un commit diferente que el binario o el paquete 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 mapas y invalida lo que Sentry debería estar coincidiendo contra.

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

Un proceso de versión que realmente resiste

Una 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 el mismo pipeline.
• Los mapas de origen se suben desde CI.
• y no desde una laptop de desarrollador.La aplicación inicia Sentry con la misma cadena de lanzamiento que CI utilizó durante la carga.
• Este último punto es más importante de lo que se espera comúnmente. 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 compilación y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions se ajusta bien al mismo modelo operativo.

Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de compilación y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions se ajusta bien al mismo modelo operativo. Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de compilación y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions se ajusta bien al mismo modelo operativo..

Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de compilación y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions se ajusta bien al mismo modelo operativo. Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de compilación y lanzamiento automáticos con GitHub Actions se ajusta bien al mismo modelo operativo. Si su equipo ya está estandarizando la automatización móvil, esta guía sobre flujos de trabajo de compilación y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions se ajusta bien al mismo modelo operativo.

A patrón de 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"

Deberás adaptar el comando de empaquetado para Android, y muchas equipos dividen las tareas específicas de plataforma en lugar de forzar a un script a realizar ambas.

La disciplina de lanzamiento supera a la scripting creativo. Elige una convención de nombres, inyecta en la aplicación en tiempo de compilación y nunca permitas que las subidas ad hoc locales 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 pago 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 rendirse.

Un informe común suena así: “La consola de dashboard 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 esta:

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. Los subespacios revelan una solicitud API y un camino de renderizado costoso.
5. Optimiza el camino de renderizado, envíe nuevamente y compare la nueva forma de la traza.

Eso es mejor que argumentar desde la intuición.

Para equipos que piensan ampliamente sobre patrones de monitoreo de aplicaciones webview o híbridas, esta publicación sobre monitoreo de rendimiento en proyectos Capacitor es digno de escaneo porque el mindset operativo es similar aunque la pila difiere.

Agregando contexto útil a errores

Los datos de rendimiento se vuelven más útiles cuando los eventos llevan 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 entre suposiciones.
• 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 capturas 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' },
  });
}

Un rastro de breadcrumb a menudo es 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.”

Cuando la instrumentación personalizada va mal, suele ir mal porque es demasiado ruidosa. No capture cada pulsación de botón en la aplicación para siempre. Capture límites, transiciones de estado y operaciones que importan al depurar. Basta con proporcionar el contexto suficiente para explicar el evento. No demasiado para ahogarlo.

Verificar y Resolver Problemas en su Integración

Debería verificar Sentry antes de enviar la aplicación, después de cambios en la línea de producción y después de SDK actualizaciones. “Funcionó hace meses” no es una prueba significativa.

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 estrelle:

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

El testing de fallas nativas debe hacerse con cuidado y solo en compilaciones de desarrollo o pruebas 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 usar la utilidad de testing de fallas nativas documentada del SDK cuando esté presente en lugar de inventar mi propio camino de falla.

¿Qué verificar en la interfaz de usuario de Sentry

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

Verifica estos campos:

• Plataforma y mecanismo. Esto ayuda a distinguir excepciones de JS de crash nativos.
• Lanzamiento 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.
• Bocadillos 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 solo flujo.

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

Trabajos de depuración comunes de Sentry React Native

Un hábito final que vale la pena es mantener una lista de comprobación de

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 en términos de la versión de la aplicación original, las trazas de pila se vuelven engañosas rápidamente

La solución es hacer que la identidad de la liberación de Sentry siga el paquete de JavaScript en vivo, no solo el binario nativo Coincidir identificadores de liberación con paquetes de JavaScript en vivoPara flujos de trabajo de actualizaciones en vivo, trate a __CAPGO_KEEP_0__ y __CAPGO_KEEP_1__ 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 no es suficiente por sí sola una vez que los paquetes pueden cambiar de manera independiente

Un patrón práctico puede verse así:

Un hábito final que vale la pena es mantener una lista de comprobación de 'verificación de monitoreo de humo' en tu proceso de liberación. Desencadena un evento JS en staging, confirma los valores de liberación y verifica las ubicaciones de origen antes de promover una compilación. release Integrar con flujos de trabajo de actualizaciones en vivo como __CAPGO_KEEP_0__ dist 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 en términos de la versión de la aplicación original, las trazas de pila se vuelven engañosas rápidamente.

La solución es hacer que la identidad de la liberación de Sentry siga el paquete de JavaScript en vivo, no solo el binario nativo.

• 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 ajusta a su modelo.
• Cargue mapas de fuentes para cada conjunto de actualizaciones 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 conjunto de actualizaciones activo actualmente, no solo de la configuración de construcción estática.

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

De esa manera, cuando un usuario golpee un error en un conjunto de actualizaciones hotfix, Sentry resuelve marcos contra el mapa de fuentes para ese parche en vivo en lugar del conjunto de almacenamiento de la aplicación más antiguo.

Esto importa con cualquier flujo de trabajo de actualización OTA. Si desea una buena introducción a los componentes 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 lanzamiento estática para cada actualización de almacenamiento posterior. Si varios paquetes comparten la misma versión de Sentry, el depurado vuelve a ser adivinanza.

Si su equipo envía correcciones fuera de los ciclos de revisión de la tienda de aplicaciones, Capgo es recomendable evaluar. Proporciona a los equipos de Capacitor una forma estructurada de entregar actualizaciones en vivo, dirigir canales, controlar los lanzamientos y recuperarse rápidamente de lanzamientos malos. Asociar eso con un nombrado disciplinado de versiones de Sentry y subidas de mapas de origen, y obtendrás un flujo de trabajo donde los errores siguen señalando a los usuarios exactos code que están ejecutando.