Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

React Native

Strukturierte Logs, JavaScript-Fehler und Abstürze aus deiner React-Native-App, über die SDKs für Swift und Android.

iOS- und Android-Apps, auf Basis der nativen SDKs

Das React-Native-SDK ist ein schlankes TurboModule über den SDKs für Swift und Android. Die nativen SDKs halten die Warteschlange auf der Festplatte, senden in Batches, wiederholen fehlgeschlagene Sendungen, führen Sessions und melden native Abstürze. Dieses Paket ergänzt, was nur JavaScript sieht: nicht abgefangene Fehler, unbehandelte Promise-Rejections, Render-Fehler von React und Screens von React Navigation.

Es braucht React Native 0.80 oder neuer mit der New Architecture und React 19. Apps laufen unter iOS 16 oder neuer und Android 7.0 (API 24) oder neuer.

Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin ist @lyrelog/react-native nicht auf npm, und die nativen SDKs, auf denen es aufbaut, sind ebenfalls nicht veröffentlicht.

Installation

pnpm add @lyrelog/react-native
cd ios && pod install

Unter iOS bringt der Pod das Swift-Paket Lyrelog über Swift Package Manager mit. Setze das Deployment Target deiner App (und die Zeile platform :ios im Podfile) auf 16.0 oder höher. Unter Android lädt Gradle com.lyrelog:lyrelog-android von Maven Central, was die Berechtigung INTERNET hinzufügt.

Starten

Starte einmal, so früh wie möglich, in index.js vor AppRegistry. Ein zweiter Aufruf behält die erste Konfiguration. Events, die vor init geloggt werden, werden ignoriert, aber setUser und setConsent, vor init aufgerufen, bleiben erhalten und werden angewendet, sobald es läuft.

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

Events gehen an https://ingest.lyrelog.com. Übergib endpoint nur, um sie woanders hinzuschicken. Er muss https sein; unverschlüsseltes http geht nur für localhost, 127.0.0.1 oder ::1 (den iOS-Simulator) und im Android-Emulator für 10.0.2.2.

Nichts im SDK wirft Exceptions in deine App. In einem Development-Build werden ein fehlender Schlüssel oder ein fehlendes natives Modul (die App wurde nach der Installation nicht neu gebaut) einmal mit console.warn gemeldet.

Events loggen

Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical, oder 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 },
});

Attribute sind kleine Felder zum Filtern und für Diagramme: Strings, Zahlen, Booleans, null, Arrays und verschachtelte Objekte bis 4 Ebenen. Die Payload ist beliebiges JSON, für die Details, die du nur liest, wenn du ein einzelnes Event öffnest. minimumLevel (Standard debug) verwirft niedrigere Level, bevor sie in den nativen Code gelangen.

Logger für jeden Bereich

Ein Logger versieht jedes Event mit seiner category. Er hat jedes Level, dazu log und captureException.

const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });

Nutzer

Lyrelog.setUser(playerId);   // attached to every following event
Lyrelog.setUser(null);       // on sign-out

Lyrelog.sessionId liefert die ID der aktuellen Session, zum Beispiel zum Anzeigen in einem Support-Screen. Die Nutzer-ID wird zwischen Starts nicht gespeichert: Rufe setUser bei jedem Start erneut auf.

Screens

Mit React Navigation verteilst du trackNavigation per Spread auf den Container:

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

Jeder angezeigte Screen loggt screen_viewed (Bereich navigation) mit screen, previous_screen und seconds_on_previous, und jedes folgende Event wird mit einem Attribut screen versehen. Als Name dient der Routenname; übergib name: (route) => ..., um einen anderen zu wählen, oder gib undefined zurück, um eine Route zu überspringen. Deine eigenen onReady und onStateChange gehören in die Optionen und laufen nach denen von Lyrelog.

Ohne React Navigation rufst du Lyrelog.screen("Settings") auf oder useLyrelogScreen("Settings") in der Komponente des Screens. Ein erneuter Aufruf von screen mit demselben Namen loggt nichts. Schalte das Taggen mit attachScreen: false ab.

Abgefangene Fehler

try {
  await store.purchase(product);
} catch (error) {
  Lyrelog.captureException(error, { category: "store" });
}

Es sendet das Event exception, das jedes SDK sendet: Level error, die Attribute error_type und error_message und eine Payload mit Name, Nachricht, Stack und bis zu 3 Ursachen (error.cause). attrs fügt eigene hinzu; level ändert das Level. In JavaScript lässt sich alles werfen: Auch ein String oder ein Objekt wird aufgezeichnet.

Die Stacks sind so, wie Hermes sie meldet. In einem Release-Build zeigen sie in das Bundle: Bewahre die Source Map des Builds auf, um sie zu lesen.

Nicht abgefangene Fehler

Mit captureErrors (standardmäßig an) klinkt sich das SDK in die Fehlerbehandlung von React Native ein:

Was passiertEventLevel, Bereichmechanism
Ein fataler JavaScript-Fehler, etwa ein throw in einem Timer oder Event-Handlerapp_crashedcritical, diagnosticsjs_fatal
Ein Render-Fehler, den keine Error Boundary abgefangen hatapp_crashedcritical, diagnosticsreact_render
Ein nicht fataler Fehler, an ErrorUtils gemeldetexception, handled: falseerrorjs_error
Eine unbehandelte Promise-Rejectionexception, handled: falseerrorunhandled_rejection

Ein fataler Fehler wird auf die Festplatte geschrieben, bevor die App beendet wird, mit bis zu 1,5 Sekunden Wartezeit, und dann gesendet, wenn es geht, sonst beim nächsten Start. Er wird als app_crashed im Bereich diagnostics erfasst, wie die nativen Absturzberichte, sodass JavaScript- und native Abstürze im Dashboard beieinanderliegen.

Jeder Fehler wird einmal aufgezeichnet. Nicht fatale, nicht abgefangene Fehler werden auf 10 pro Minute begrenzt, und derselbe Fehler höchstens einmal alle 10 Sekunden; Lyrelog.skippedErrors zählt, was ausgelassen wurde. Die zuvor installierten Handler laufen weiter: die Red Box und LogBox in der Entwicklung, der Absturz im Release.

Error Boundaries

import { LyrelogErrorBoundary } from "@lyrelog/react-native";

<LyrelogErrorBoundary
  category="feed"
  fallback={({ error, reset }) => <Retry onPress={reset} />}
>
  <Feed />
</LyrelogErrorBoundary>

Ein Render-Fehler in den Komponenten darunter wird als exception mit mechanism: error_boundary und dem Component Stack von React (component_stack in der Payload) aufgezeichnet, und stattdessen wird fallback angezeigt. onError wird aufgerufen, nachdem er aufgezeichnet wurde. Ohne Fallback rendert die Boundary nach einem Fehler nichts.

Native Abstürze

Diese kommen von den nativen SDKs (captureCrashes, standardmäßig an) und werden beim nächsten Start im Bereich diagnostics gesendet: nicht abgefangene JVM-Exceptions unter Android als app_crashed; unter iOS die Berichte von MetricKit, Abstürze als app_crashed und Hänger als app_hung. Siehe Abstürze unter Android und Abstürze und Hänger in Swift.

Unter Android beendet ein fataler JavaScript-Fehler die App mit einer Java-Exception. Sobald das app_crashed aus JavaScript auf der Festplatte liegt, umgeht diese Exception den Recorder des Android-SDKs, sodass derselbe Absturz nicht doppelt gemeldet wird.

Umgebungen und Plattform

Die Umgebung ist die des nativen SDKs: unter iOS development in Debug-Builds, testflight in TestFlight, sonst production; unter Android development, wenn die App debuggable ist, sonst production. Deine eigenen Debug-Builds senden development, während das Dashboard mit production öffnet: Wähle development in der oberen Leiste, um sie zu sehen.

Die Plattform ist ios oder android. Beides lässt sich überschreiben:

Lyrelog.init({
  apiKey: key,
  environment: isBeta ? "beta" : undefined,   // undefined = detected
});

Events nennen dieses Paket und das native SDK darunter (sdk ist lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 oder 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 behält Events auf dem Gerät, ohne sie zu senden. Ohne erteilte Einwilligung wird nichts hochgeladen. Die Einwilligung wird zwischen Starts nicht gespeichert: Speichere die Entscheidung der Person selbst (zum Beispiel mit AsyncStorage) und übergib sie jedes Mal an init.

Attestierung

attest (standardmäßig an) weist die App unter iOS mit App Attest und unter Android mit Key Attestation nach, sodass ihre Events als verifiziert gespeichert werden. Siehe Verifizierte Events.

Optionen

OptionStandardWas
apiKeyDer Ingest-Schlüssel des Projekts, lyr_ing_...
endpointhttps://ingest.lyrelog.comWohin Events gehen
consentgrantedgranted, pending oder denied
environmenterkanntJeder Name
platformios / androidWelcher Teil des Produkts sendet
minimumLeveldebugNiedrigere Level werden verworfen
flushIntervalMs15000Wie oft Events aus der Warteschlange im Vordergrund gesendet werden
sessionTimeoutMs30 MinutenEine neue Session nach so langer Zeit ohne Event
maxDiskBytes20 MBWas auf dem Gerät warten darf; die ältesten gehen zuerst
redactKeysDEFAULT_REDACT_KEYSSchlüssel in Attributen und Payload, deren Werte ersetzt werden. Deine Liste ersetzt die Standardwerte; [] schaltet es ab
captureErrorstrueJavaScript-Fehler, die niemand abgefangen hat
captureCrashestrueNative Abstürze
attachScreentrueDas Attribut screen auf jedem Event
attesttrueApp Attest und Key Attestation
mirrorToNativeLogfalseJedes Event zusätzlich in der Konsole von Xcode oder in logcat ausgeben

Flush und Stopp

Der Wechsel in den Hintergrund sendet bereits, du brauchst es also selten.

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

Nach close kann init erneut aufgerufen werden.