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 solucionarlo sin adivinar. La trampa 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
  • Lo que 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
• Integrando con flujos 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 proporciona contexto útil no publicitario 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 pregunta algunas cosas que los desarrolladores a menudo pasan demasiado rápido:

• Selección de proyecto. Elige el proyecto Sentry real que planeas usar en producción, no un sandbox temporal que olvidarás actualizar más tarde.
• Cambios nativosSí, por favor. La captura de errores solo con JavaScript no es suficiente para aplicaciones móviles.
• Características opcionalesSí, por favor. 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.jsony cambios nativos bajo ios y androidy un bloque de inicialización en tu archivo de entrada de la aplicación.

Un inicio típico 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 arborescencia de tu aplicación monte. Si también estás trabajando a través de la pulido de inicio, esta guía a 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 persigas la perfección. El objetivo inmediato es simple: lanza la aplicación, activa 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 generalmente 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 el subida de símbolos o la coincidencia 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. Revisa android/build.gradle, android/app/build.gradley 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 utiliza sabores de producto o múltiples tipos de compilación.
3. Los resultados de ProGuard o R8 se tienen en cuenta si sus 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 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 asistente 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 e 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 a subir 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 determinista en iOS, Android y JavaScript

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 versiones. Luego llega el primer problema serio en producción y la pila de llamadas está minimizada, 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 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 mapas y invalida lo que Sentry debería estar coincidiendo contra.

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 administrar versiones de Sentry y mapas de origen para React Native.

Un proceso de versión que realmente funciona correctamente. 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 CIno 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 construcción y lanzamiento automáticos con __CAPGO_KEEP_0__ Actions automatic build and release workflows with GitHub Actions El correcto funcionamiento de Sentry depende de que los mapas de origen estén correctamente asociados con el identificador de lanzamiento emitido por la aplicación en tiempo de ejecución.

A un patrón práctico de script de CI

Utilice un script como este en CI y alimente valores de su 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á 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 a la programación creativa. Elige una convención de nombres, inyecta en la aplicación en tiempo de compilación y nunca permita 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 envió, no el code que cree haber enviado.

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 consola de dashboard es lenta.” Eso no es suficiente para depurar. Lenta 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 problema 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 subintervalos revelan un API solicitud y un camino de renderizado costoso.
5. Optimiza el camino de renderizado, envíe nuevamente y compare la forma de la nueva traza.

Es mejor que argumentar desde la intuición.

Para equipos que piensan ampliamente sobre patrones de monitoreo de aplicaciones de webview o híbridas, este escrito sobre monitoreo de rendimiento en proyectos de Capacitor es recomendable revisar porque la mentalidad operativa es similar aunque la pila difiere.

Agregar 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 en la oscuridad.
• 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 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, y 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 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 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 de nativos.
• Versión y dist. Si están en blanco o están mal, los mapas de fuentes y la simbolicación se desviarán.
• Frames de pila. Las ubicaciones de fuentes legibles deberían aparecer para los mapas de JavaScript subidos 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 siga ajustando la aplicación code. Eso suele ser un problema de artefacto de compilación.

Problemas comunes de depuración de Sentry React Native

Una costumbre final que vale la pena es mantener una lista de comprobación de pruebas de humo de monitoreo pequeña en tu proceso de liberación. Disparar un evento JS en staging, confirmar valores de liberación y verificar 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 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 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 UI 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 importando, pero ya no es suficiente una vez que los paquetes pueden cambiar independientemente

Un patrón práctico puede verse así

• Utilice la versión de la aplicación nativa como parte del nombre de la versión base.
• Agregue 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 de actualización en vivo, Sentry resuelve marcos contra el mapa de fuentes para esa actualización en vivo en lugar del paquete de almacenamiento de la tienda más antiguo.

Esto importa con cualquier flujo de trabajo de actualización en vivo. 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 el seguimiento de versiones:

El principal error a evitar es reutilizar una cadena de lanzamiento estática para cada actualización de post-almacenamiento. 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. Le da a los equipos Capacitor una forma estructurada de entregar actualizaciones en vivo, dirigir canales, controlar los lanzamientos y recuperarse rápidamente de versiones malas. Pair eso con la nomenclatura de versiones de Sentry disciplinada 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.