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, 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, la pila, la versión que lo envió y suficiente contexto para arreglarlo sin adivinar. El catch es que la instalación básica es la parte fácil. Las partes dolorosas vienen después: integración nativa, simbolización, mapas de fuentes, nombres de versión y mantener todo eso alineado cuando tu 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, builds de App Store, lanzamientos de Android y paquetes de JavaScript que no siempre provienen del binario original.

Contenido de la Tabla

• Getting Started with the Sentry SDK
  • Empezar con Sentry __CAPGO_KEEP_0__
  • Lo que necesitas antes de instalar
• Corriendo el asistente y revisando el resultado
  • Configurando proyectos de iOS y Android nativos
  • ¿Qué cambió en Android
  • Configuración nativa que ahorra tiempo más adelante
• Automatizar lanzamientos y mapas de origen
  • ¿Por qué los subidas manuales fallan en la práctica?
  • Un proceso de lanzamiento que realmente funciona
  • Un patrón de script de CI práctico
• Capturar datos de rendimiento y eventos personalizados
  • Seguimiento de una pantalla lenta en lugar de adivinar
  • Agregar contexto útil a errores
• Verificar y depurar su integración
  • Activar eventos de prueba de manera segura
  • ¿Qué verificar en la interfaz de usuario de Sentry
  • Resolución común de problemas de Sentry React Native
• Integración con flujos de trabajo como Live Update y Capgo
  • Asociar identificadores de lanzamiento a paquetes en vivo

Comenzar 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 que el primer instalación manualmente suele llevar a pequeñas incompatibilidades que no notarás hasta el primer crash en producción.

Lo que 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 en 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 proyectoElige el proyecto Sentry real que planeas usar en producción, no un entorno de pruebas temporal que olvidarás actualizar más tarde.
• Cambios nativos. Diga sí. 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 habilite todo de manera ciega el primer día si tu equipo no revisará los datos resultantes.

Ejecución del asistente y revisión del resultado

Después del final del asistente, inspeccione los cambios en lugar de confiar en ellos sin revisión. Debe ver un paquete de Sentry en package.jsonCambios nativos bajo ios and androidy un 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 a SDK dónde enviar eventos. Trátalo como configuración, no como un elemento de caja fuerte 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 Sentry correcto en cada entorno.

A practical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. If you’re also working through startup polish, this guide to Configuración de pantalla de inicio de React Native es útil porque el orden de inicio de code a menudo coincide con dónde los equipos colocan la inicialización de Sentry.

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

At this stage, don’t chase perfection. The immediate goal is simple: launch the app, trigger a JavaScript exception later in the article, and confirm events reach Sentry. Once that’s working, the native and release layers become much easier to reason about.

Configurando proyectos nativos 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

Abra el proyecto de iOS y revise qué cambió el asistente. En una aplicación React Native básica, eso suele significar actualizaciones alrededor de las fases de inicio y compilación de la aplicación. Está buscando hooks de inicialización de Sentry y pasos de carga relacionados con su proceso de compilación.

In Xcode, revise estos lugares:

• Delegado de aplicación de inicio code. La aplicación necesita inicialización nativa de Sentry temprano en el arranque.
• Fases de compilación. Busque cualquier script de carga de Sentry relacionado con símbolos de depuración o manejo de mapas de fuentes.
• Build settings and archive behaviorLos 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 del arranque del 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 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 ser el subir símbolos o el ajuste de la versión de liberación.

¿Qué cambió en Android

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

Cosas a verificar:

1. Se aplica el plugin Gradle de Sentry Los artefactos de la versión pueden 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 lanzamiento reducen o desobfuscan code.

Un error común en Android es asumir que una ejecución de depuración local exitosa prueba que la configuración de lanzamiento es correcta. No lo es. La ruta de lanzamiento 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 seguimiento alineado con cada variante de compilación.

Configuración nativa que ahorra tiempo más adelante

No se detenga en “el mago modificó archivos.” Verifique el comportamiento directamente.

Use esta lista de verificación:

• Archivar una compilación de iOS localmente y confirme que la compilación no falla durante el procesamiento de símbolos.
• Crear una compilación de lanzamiento de Android y revisar los registros de CI relacionados con Sentry.
• Check the package name and bundle identifier mapping Confirme las convenciones de nombres de lanzamiento ahora
• Confirma convenciones de nombres de lanzamiento ahoraVerifique el comportamiento de seguimiento directamente.

Aquí está lo que no funciona bien normalmente:

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

Automatizar Lanzamientos y Mapas de Fuentes

Si hay un lugar donde las configuraciones de Sentry React Native fallan, 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 seguimiento está minimizada, la versión falta o el archivo de mapas de fuentes pertenecía a un bundle diferente.

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

¿Por qué las subidas manuales fallan en la práctica?

Los modos de falla son predecibles:

• Alguien se olvida de subir los mapas después de una corrección de última noche.
• Los archivos subidos pertenecen a un commit diferente que el binario o el paquete OTA que los usuarios ejecutan.
• El nombre de la versión cambia ligeramente entre los pasos de iOS, Android y CI.
• Una reconstrucción ocurre después de subir el mapa y invalida lo que Sentry debería estar coincidiendo contra.

Por eso no recomiendo un enfoque de ‘documentar los pasos en Notion’. Funciona hasta que una versión urgente sale bajo presión.

Un proceso de lanzamiento que realmente funciona

Una configuración confiable tiene algunas propiedades:

• Los IDs de lanzamiento se generan una vez y se reutilizan en todas partes.
• Los pasos de compilación, empaquetado y carga ocurren en el mismo pipeline.
• Los mapas de fuentes 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.

Ese último punto es más importante de lo que se espera comúnmente. No solo necesitas mapas de fuentes en Sentry. Necesitas los mapas de fuentes 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 flujo de trabajo de compilación y lanzamiento automático con GitHub Actions Un patrón práctico de script de CI

Un patrón práctico de script de CI

Utilice un script como este en CI y alimente valores desde 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"

You’ll need to adapt the bundle command for Android, and many teams split platform-specific jobs instead of forcing one script to do both. That’s fine. What matters is consistency.

Disciplina de lanzamiento supera la programación ingeniosa. Para React Native, prefiero almacenar la cadena de lanzamiento en una ubicación de configuración generada por la compilación y leerla durante

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,
});

The payoff is simple. When an event arrives, Sentry can map the minified frame back to the code you shipped, not the code you think you shipped.

Capturando datos de rendimiento y eventos personalizados

Se te dicen qué se rompió. La trazabilidad de rendimiento te dice qué sintieron los usuarios antes de rendirse.

A un informe común suena así: “La interfaz de usuario es lenta.” Eso no es suficiente para depurar. ¿Dónde es lento? En la navegación? Durante la carga de datos? Mientras se renderiza un gráfico pesado? Sentry se vuelve útil aquí cuando dejas de tratarlo como una bandeja de errores y comienzas a instrumentar el comportamiento de la aplicación.

Rastrear una pantalla lenta en lugar de adivinar

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

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

Si utilizas React Navigation, conecta la integración para que las transiciones de pantalla produzcan datos de trazabilidad. Luego reproduce 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 dashboard:

1. Un usuario abre la pantalla principal después de iniciar sesión.
2. La navegación se completa, pero el contenido aparece tarde.
3. El rastro muestra que la transacción de pantalla es larga.
4. Las spans de hijo revelan un API solicitud y un camino de renderizado costoso.
5. Optimiza el camino de renderizado, envía de nuevo y compara la nueva forma del rastro.

Es mejor que argumentar desde la intuición.

Para equipos que piensan ampliamente sobre patrones de monitoreo de aplicaciones híbridas o de vista web. monitoreo de rendimiento en proyectos Capacitor es digno de una lectura rápida porque la mentalidad operativa es similar aunque la pila sea diferente.

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 propósito:

• 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.
• Custom tags 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.

Ejemplo:

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 bocadillos suele ser 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 por ser demasiado ruidosa. No capturas cada pulsación de botón en la aplicación para siempre. Captura límites, transiciones de estado y operaciones que importan al depurar. Basta con contexto para explicar el evento. No basta para ahogarlo.

Verificar y depurar su integración

Verifique Sentry antes de enviar, después de cambios en la línea de producción y después de actualizaciones SDK. “Funcionaba hace meses” no es un test significativo.

La forma más limpia es desencadenar fallas controladas para ambos caminos de JavaScript y nativos, luego inspecciona cómo llegan a Sentry.

Desencadenar 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 haga que la aplicación se caiga:

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

El testing de crash nativo 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 y la configuración de plataforma de SDK, por lo que prefiero utilizar la utilidad de prueba de crash nativa documentada de SDK cuando esté presente en lugar de inventar mi propio camino de crash.

¿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 JavaScript de crash nativos.
• Versión de lanzamiento y distribución. 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.
• Breadcrumbs y etiquetasVerifique que su contexto personalizado ha llegado.
• EntornoVerifique que los eventos de desarrollo y producción no se mezclen en un solo flujo.

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

Problemas de depuración comunes de Sentry React Native

Una buena costumbre que vale la pena mantener es tener una lista de comprobación de pruebas de monitoreo ‘fumigación’ pequeña en tu proceso de lanzamiento. Dispara un evento JS en staging, confirma los valores de lanzamiento y verifica las ubicaciones de origen antes de promover una compilación

Integrar con Live Update Flujos de trabajo como Capgo

Las actualizaciones en vivo cambian el modelo de lanzamiento. 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 Identidad de lanzamiento Sentry sigue el paquete en vivono solo al binario nativo

Identificadores de lanzamiento coincidentes con paquetes en vivo

Para flujos de trabajo como live update release 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 no es suficiente por sí sola una vez que los conjuntos pueden cambiar de manera independiente.

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 o identificador de paquete live update.
• Utilice dist para la diferenciación de canal o construcción cuando se adapta a tu modelo.
• Cargue 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 iniciar, 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 golpea un error en un paquete de hotfix, Sentry resuelve marcos contra el mapa de fuentes para ese hotfix 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 componentes en movimiento detrás de ese modelo de entrega, esta explicación de how live updates work in Capacitor apps es una referencia sólida.

Aquí está el tipo de visión operativa a la que aspiran los equipos cuando combinan metadatos de actualización con seguimiento de lanzamiento:

El principal error a evitar es reutilizar una cadena de lanzamiento estática para cada actualización posterior a la tienda. Si varios paquetes comparten la misma versión de Sentry, el depurado vuelve a ser adivinanzas.

If your team ships fixes outside app store review cycles, Capgo es merecedor de evaluación. Proporciona a los equipos de Capacitor un método estructurado para entregar actualizaciones en vivo, dirigir canales, controlar los despliegues y recuperarse rápidamente de los lanzamientos malos. Ponga eso junto con la denominación disciplinada de versiones de Sentry y subidas de mapas de fuentes, y obtendrá un flujo de trabajo donde los errores aún señalan a los usuarios que ejecutan exactamente code.