React Native
Logs estructurados, errores de JavaScript y crashes desde tu app de React Native, sobre los SDK de Swift y Android.
El SDK de React Native es un TurboModule ligero sobre los SDK de Swift y Android. Los SDK nativos guardan la cola en disco, envían por lotes, reintentan, mantienen las sesiones y registran los crashes nativos. Este paquete añade lo que solo ve JavaScript: errores no capturados, promesas rechazadas sin gestionar, errores de renderizado de React y pantallas de React Navigation.
Necesita React Native 0.80 o posterior con la New Architecture, y React 19. Las apps funcionan en iOS 16 o posterior y en Android 7.0 (API 24) o posterior.
Versión preliminar interna: este paquete aún no está publicado. Hasta que lo esté,
@lyrelog/react-native no está en npm, y los SDK nativos sobre los que se apoya tampoco están
publicados.
Instalación
pnpm add @lyrelog/react-native
cd ios && pod installEn iOS, el pod trae el paquete Swift Lyrelog a través de Swift Package Manager. Pon el
deployment target de tu app (y la línea platform :ios del Podfile) en 16.0 o posterior. En
Android, Gradle descarga com.lyrelog:lyrelog-android de Maven Central, que añade el permiso
INTERNET.
Primeros pasos
Arranca el SDK una sola vez y lo antes posible, en index.js, antes de AppRegistry. Una
segunda llamada mantiene la primera configuración. Los eventos registrados antes de init se ignoran,
pero setUser y setConsent llamados antes de init se guardan y se aplican cuando se ejecuta.
import { AppRegistry } from "react-native";
import { Lyrelog } from "@lyrelog/react-native";
import App from "./src/App";
Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
});
AppRegistry.registerComponent("main", () => App);Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio.
Tiene que ser https; http sin cifrar solo funciona con localhost, 127.0.0.1 o ::1 (el
simulador de iOS), y en el emulador de Android con 10.0.2.2.
Nada en el SDK lanza excepciones hacia tu app. En una build de desarrollo, una clave que falta o un
módulo nativo que falta (no se recompiló la app después de instalarlo) se avisa una vez con
console.warn.
Registrar eventos
Una función por nivel: trace, debug, info, notice, warning, error, critical, o
log(level, message, options).
Lyrelog.info("checkout_done", { attrs: { items: 3, latency_ms: ms } });
Lyrelog.error("payment_declined", {
category: "checkout",
attrs: { code: 51 },
payload: { response },
});Los atributos son campos pequeños para filtrar y hacer gráficas: cadenas, números, booleanos,
null, arrays y objetos anidados de hasta 4 niveles. El payload es cualquier JSON, para el detalle
que solo lees al abrir un evento. minimumLevel (por defecto debug) descarta los niveles
inferiores antes de que pasen al código nativo.
Loggers por área
Un logger pone su category en cada evento. Tiene todos los niveles, además de log y
captureException.
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });Usuarios
Lyrelog.setUser(playerId); // attached to every following event
Lyrelog.setUser(null); // on sign-outLyrelog.sessionId da el id de la sesión actual, por ejemplo para mostrarlo en una pantalla de
soporte. El id de usuario no se guarda entre arranques: vuelve a llamar a setUser en cada
arranque.
Pantallas
Con React Navigation, expande trackNavigation en el contenedor:
import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { trackNavigation } from "@lyrelog/react-native";
const navigationRef = createNavigationContainerRef();
export default function App() {
return (
<NavigationContainer ref={navigationRef} {...trackNavigation(navigationRef)}>
{/* your navigators */}
</NavigationContainer>
);
}Cada pantalla que se muestra registra screen_viewed (área navigation) con screen,
previous_screen y seconds_on_previous, y cada evento siguiente se etiqueta con un atributo
screen. El nombre es el de la ruta; pasa name: (route) => ... para elegir otro, o devuelve
undefined para saltarte una ruta. Tus propios onReady y onStateChange van en las opciones y se
ejecutan después de los de Lyrelog.
Sin React Navigation, llama a Lyrelog.screen("Settings"), o a useLyrelogScreen("Settings") en
el componente de la pantalla. Llamar a screen otra vez con el mismo nombre no registra nada.
Desactiva el etiquetado con attachScreen: false.
Errores que capturas
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}Envía el evento exception que envían todos los SDK: nivel error, los atributos error_type y
error_message, y un payload con el nombre, el mensaje, el stack y hasta 3 causas
(error.cause). attrs añade los tuyos; level cambia el nivel. En JavaScript se puede lanzar
cualquier cosa: una cadena o un objeto también se registran.
Los stacks son tal como los da Hermes. En una build de release apuntan al bundle: guarda el source map de la build para poder leerlos.
Errores que nadie capturó
Con captureErrors (activado por defecto), el SDK se engancha al manejo de errores de React
Native:
| Qué pasa | Evento | Nivel, área | mechanism |
|---|---|---|---|
| Un error fatal de JavaScript, como un throw en un temporizador o en un event handler | app_crashed | critical, diagnostics | js_fatal |
| Un error de renderizado que ningún error boundary capturó | app_crashed | critical, diagnostics | react_render |
Un error no fatal notificado a ErrorUtils | exception, handled: false | error | js_error |
| Una promesa rechazada sin gestionar | exception, handled: false | error | unhandled_rejection |
Un error fatal se escribe en disco antes de que la app se cierre, esperando hasta 1,5 segundos, y
se envía en ese momento si se puede y, si no, en el siguiente arranque. Es app_crashed en el área
diagnostics, igual que los informes de crash nativos, así que los crashes de JavaScript y los
nativos aparecen juntos en el panel.
Cada error se registra una sola vez. Los errores no capturados que no son fatales tienen un tope de
10 por minuto, y el mismo error como mucho una vez cada 10 segundos; Lyrelog.skippedErrors cuenta
lo que se ha quedado fuera. Los handlers que había antes siguen ejecutándose: la pantalla roja y
LogBox en desarrollo, el crash en release.
Error boundaries
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>Un error de renderizado por debajo de él se registra como exception con
mechanism: error_boundary y el component stack de React (component_stack en el payload), y se
muestra fallback en su lugar. onError se llama después de registrarlo. Sin fallback, no
renderiza nada después de un error.
Crashes nativos
Son los de los SDK nativos (captureCrashes, activado por defecto), y se envían en el siguiente
arranque en el área diagnostics: en Android, las excepciones de la JVM no capturadas, como
app_crashed; en iOS, los informes de MetricKit, los crashes como app_crashed y los bloqueos como
app_hung. Consulta crashes en Android y
crashes y bloqueos en Swift.
En Android, un error fatal de JavaScript cierra la app con una excepción de Java. Una vez que el
app_crashed de JavaScript está en disco, esa excepción se salta el registrador de crashes del SDK de Android,
para que el mismo crash no se notifique dos veces.
Entornos y plataforma
El entorno es el del SDK nativo: en iOS, development en las builds de debug, testflight en
TestFlight y production en cualquier otro caso; en Android, development cuando la app es
depurable y production en cualquier otro caso. Tus propias builds de debug envían
development, mientras que el panel se abre en production: elige development en la barra
superior para verlas.
La plataforma es ios o android. Puedes sobrescribir cualquiera de los dos:
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});Los eventos nombran este paquete y el SDK nativo que tiene por debajo (sdk es
lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 o lyrelog-react-native/0.1.0 lyrelog-android/0.1.0).
Consentimiento
Lyrelog.init({ apiKey: key, consent: "pending" });
// later, when the person chooses:
Lyrelog.setConsent("granted"); // sends, including what was kept while pending
Lyrelog.setConsent("denied"); // deletes everything and stops recordingpending guarda los eventos en el dispositivo sin enviarlos. No se sube nada si no se ha concedido
el consentimiento. El consentimiento no se guarda entre arranques: guarda tú la elección de la
persona (por ejemplo, con AsyncStorage) y pásala a init cada vez.
Atestación
attest (activado por defecto) demuestra la app con App Attest en iOS y con Key Attestation en
Android, para que sus eventos se guarden como verificados. Consulta
Eventos verificados.
Opciones
| Opción | Por defecto | Qué es |
|---|---|---|
apiKey | La clave de ingesta del proyecto, lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | Adónde van los eventos |
consent | granted | granted, pending o denied |
environment | detectado | Cualquier nombre |
platform | ios / android | Qué parte del producto envía |
minimumLevel | debug | Los niveles inferiores se descartan |
flushIntervalMs | 15000 | Cada cuánto se envían los eventos en cola en primer plano |
sessionTimeoutMs | 30 minutos | Una sesión nueva tras este tiempo sin ningún evento |
maxDiskBytes | 20 MB | Lo que puede esperar en el dispositivo; los más antiguos se descartan primero |
redactKeys | DEFAULT_REDACT_KEYS | Claves de atributos y de payload cuyos valores se sustituyen. Tu lista sustituye a la predeterminada; [] desactiva la ocultación |
captureErrors | true | Errores de JavaScript que nadie capturó |
captureCrashes | true | Crashes nativos |
attachScreen | true | El atributo screen en cada evento |
attest | true | App Attest y Key Attestation |
mirrorToNativeLog | false | Imprime además cada evento en la consola de Xcode o en logcat |
Vaciar la cola y detener
Pasar a segundo plano ya envía, así que rara vez te hará falta.
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stopDespués de close se puede volver a llamar a init.