Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

React Native

Des logs structurés, les erreurs JavaScript et les plantages de votre app React Native, par-dessus les SDK Swift et Android.

Apps iOS et Android, par-dessus les SDK natifs

Le SDK React Native est un TurboModule léger par-dessus les SDK Swift et Android. Les SDK natifs gardent la file sur disque, envoient par lots, réessaient, gèrent les sessions et remontent les plantages natifs. Ce package ajoute ce que seul JavaScript voit : les erreurs non interceptées, les rejets de promesse non gérés, les erreurs de rendu React et les écrans de React Navigation.

Il nécessite React Native 0.80 ou plus récent avec la New Architecture, et React 19. Les apps tournent sur iOS 16 ou plus récent et sur Android 7.0 (API 24) ou plus récent.

Préversion interne : ce package n'est pas encore publié. D'ici là, @lyrelog/react-native n'est pas sur npm, et les SDK natifs sur lesquels il repose ne sont pas publiés non plus.

Installation

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

Sur iOS, le pod récupère le package Swift Lyrelog via Swift Package Manager. Réglez la deployment target de votre app (et la ligne platform :ios du Podfile) sur 16.0 ou plus. Sur Android, Gradle récupère com.lyrelog:lyrelog-android depuis Maven Central, ce qui ajoute la permission INTERNET.

Démarrage

Démarrez une seule fois, le plus tôt possible, dans index.js, avant AppRegistry. Un second appel garde la première configuration. Les événements journalisés avant init sont ignorés, mais setUser et setConsent appelés avant init sont conservés et appliqués au démarrage.

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

Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer ailleurs. Il doit être en https ; le http simple ne fonctionne que pour localhost, 127.0.0.1 ou ::1 (le simulateur iOS), et sur l'émulateur Android pour 10.0.2.2.

Rien dans le SDK ne lève d'exception dans votre app. Dans un build de développement, une clé manquante ou un module natif manquant (l'app n'a pas été recompilée après l'installation) est signalé une fois avec console.warn.

Journaliser des événements

Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou 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 },
});

Les attributs sont de petits champs pour filtrer et faire des graphiques : chaînes, nombres, booléens, null, tableaux et objets imbriqués jusqu'à 4 niveaux. Le payload est n'importe quel JSON, pour le détail que vous ne lisez qu'en ouvrant un événement. minimumLevel (par défaut debug) écarte les niveaux inférieurs avant qu'ils ne passent au code natif.

Un logger par domaine

Un logger appose sa category sur chaque événement. Il a tous les niveaux, plus log et captureException.

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

Utilisateurs

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

Lyrelog.sessionId donne l'id de la session en cours, par exemple pour l'afficher dans un écran d'assistance. L'id utilisateur n'est pas conservé d'un lancement à l'autre : appelez de nouveau setUser à chaque lancement.

Écrans

Avec React Navigation, décomposez (spread) trackNavigation dans les props du conteneur :

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

Chaque écran affiché journalise screen_viewed (domaine navigation) avec screen, previous_screen et seconds_on_previous, et chaque événement suivant est marqué d'un attribut screen. Le nom est celui de la route ; passez name: (route) => ... pour en choisir un autre, ou renvoyez undefined pour ignorer une route. Vos propres onReady et onStateChange vont dans les options et s'exécutent après ceux de Lyrelog.

Sans React Navigation, appelez Lyrelog.screen("Settings"), ou useLyrelogScreen("Settings") dans le composant de l'écran. Rappeler screen avec le même nom ne journalise rien. Désactivez le marquage avec attachScreen: false.

Les erreurs que vous interceptez

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

Cela envoie l'événement exception qu'envoient tous les SDK : niveau error, les attributs error_type et error_message, et un payload avec le nom, le message, la stack et jusqu'à 3 causes (error.cause). attrs ajoute les vôtres ; level change le niveau. En JavaScript, on peut lever n'importe quoi : une chaîne ou un objet est enregistré aussi.

Les stacks sont telles que Hermes les rapporte. Dans un build de release, elles pointent dans le bundle : gardez la source map du build pour les lire.

Les erreurs que personne n'a interceptées

Avec captureErrors (activé par défaut), le SDK se branche sur la gestion des erreurs de React Native :

Ce qui se passeÉvénementNiveau, domainemechanism
Une erreur JavaScript fatale, comme un throw dans un timer ou un gestionnaire d'événementapp_crashedcritical, diagnosticsjs_fatal
Une erreur de rendu qu'aucune error boundary n'a interceptéeapp_crashedcritical, diagnosticsreact_render
Une erreur non fatale remontée à ErrorUtilsexception, handled: falseerrorjs_error
Un rejet de promesse non géréexception, handled: falseerrorunhandled_rejection

Une erreur fatale est écrite sur disque avant que l'app ne se ferme, avec une attente d'au plus 1,5 seconde, et elle est envoyée tout de suite si possible, sinon au lancement suivant. C'est un app_crashed dans le domaine diagnostics, comme les rapports de plantage natifs : les plantages JavaScript et natifs se retrouvent ainsi côte à côte dans le tableau de bord.

Chaque erreur est enregistrée une seule fois. Les erreurs non interceptées qui ne sont pas fatales sont plafonnées à 10 par minute, et la même au plus une fois toutes les 10 secondes ; Lyrelog.skippedErrors compte ce qui a été laissé de côté. Les handlers déjà en place s'exécutent toujours : l'écran rouge et LogBox en développement, le plantage en release.

Error boundaries

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

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

Une erreur de rendu dans l'un de ses enfants est enregistrée comme exception avec mechanism: error_boundary et la stack de composants de React (component_stack dans le payload), et fallback s'affiche à la place. onError est appelé une fois l'erreur enregistrée. Sans fallback, rien n'est affiché après une erreur.

Plantages natifs

Ce sont ceux des SDK natifs (captureCrashes, activé par défaut), envoyés au lancement suivant dans le domaine diagnostics : sur Android, les exceptions JVM non interceptées, en app_crashed ; sur iOS, les rapports MetricKit, les plantages en app_crashed et les blocages en app_hung. Voir les plantages sur Android et les plantages et blocages en Swift.

Sur Android, une erreur JavaScript fatale termine l'app par une exception Java. Une fois l'app_crashed JavaScript sur disque, cette exception contourne l'enregistreur du SDK Android, si bien que le même plantage n'est pas remonté deux fois.

Environnements et plateforme

L'environnement est celui du SDK natif : sur iOS, development dans les builds de debug, testflight sur TestFlight, production sinon ; sur Android, development quand l'app est débogable, production sinon. Vos propres builds de debug envoient development, alors que le tableau de bord s'ouvre sur production : choisissez development dans la barre du haut pour les voir.

La plateforme est ios ou android. Vous pouvez remplacer l'un ou l'autre :

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

Les événements nomment ce package et le SDK natif sous-jacent (sdk vaut lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 ou 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 garde les événements sur l'appareil sans les envoyer. Rien n'est envoyé tant que le consentement n'est pas accordé. Le consentement n'est pas conservé d'un lancement à l'autre : stockez vous-même le choix de la personne (par exemple avec AsyncStorage) et passez-le à init à chaque fois.

Attestation

attest (activé par défaut) prouve l'app avec App Attest sur iOS et Key Attestation sur Android, pour que ses événements soient enregistrés comme vérifiés. Voir Événements vérifiés.

Options

OptionPar défautRôle
apiKeyLa clé d'ingestion du projet, lyr_ing_...
endpointhttps://ingest.lyrelog.comOù vont les événements
consentgrantedgranted, pending ou denied
environmentdétectéN'importe quel nom
platformios / androidQuelle partie du produit envoie
minimumLeveldebugLes niveaux inférieurs sont écartés
flushIntervalMs15000La fréquence d'envoi des événements en file au premier plan
sessionTimeoutMs30 minutesUne nouvelle session après ce délai sans événement
maxDiskBytes20 MBCe qui peut attendre sur l'appareil ; les plus anciens partent en premier
redactKeysDEFAULT_REDACT_KEYSLes clés d'attributs et de payload dont les valeurs sont remplacées. Votre liste remplace celle par défaut ; [] désactive le masquage
captureErrorstrueLes erreurs JavaScript que personne n'a interceptées
captureCrashestrueLes plantages natifs
attachScreentrueL'attribut screen sur chaque événement
attesttrueApp Attest et Key Attestation
mirrorToNativeLogfalseAffiche aussi chaque événement dans la console de Xcode ou dans logcat

Vider la file et arrêter

Le passage en arrière-plan envoie déjà : vous en aurez donc rarement besoin.

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

Après close, init peut être rappelée.