Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

React Native

Logs estructurados, errores de JavaScript y crashes desde tu app de React Native, sobre los SDK de Swift y Android.

Apps de iOS y Android, sobre los SDK nativos

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 install

En 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-out

Lyrelog.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é pasaEventoNivel, áreamechanism
Un error fatal de JavaScript, como un throw en un temporizador o en un event handlerapp_crashedcritical, diagnosticsjs_fatal
Un error de renderizado que ningún error boundary capturóapp_crashedcritical, diagnosticsreact_render
Un error no fatal notificado a ErrorUtilsexception, handled: falseerrorjs_error
Una promesa rechazada sin gestionarexception, handled: falseerrorunhandled_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).

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 recording

pending 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ónPor defectoQué es
apiKeyLa clave de ingesta del proyecto, lyr_ing_...
endpointhttps://ingest.lyrelog.comAdónde van los eventos
consentgrantedgranted, pending o denied
environmentdetectadoCualquier nombre
platformios / androidQué parte del producto envía
minimumLeveldebugLos niveles inferiores se descartan
flushIntervalMs15000Cada cuánto se envían los eventos en cola en primer plano
sessionTimeoutMs30 minutosUna sesión nueva tras este tiempo sin ningún evento
maxDiskBytes20 MBLo que puede esperar en el dispositivo; los más antiguos se descartan primero
redactKeysDEFAULT_REDACT_KEYSClaves de atributos y de payload cuyos valores se sustituyen. Tu lista sustituye a la predeterminada; [] desactiva la ocultación
captureErrorstrueErrores de JavaScript que nadie capturó
captureCrashestrueCrashes nativos
attachScreentrueEl atributo screen en cada evento
attesttrueApp Attest y Key Attestation
mirrorToNativeLogfalseImprime 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 stop

Después de close se puede volver a llamar a init.