React Native
Des logs structurés, les erreurs JavaScript et les plantages de votre app React Native, par-dessus les SDK Swift et Android.
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 installSur 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-outLyrelog.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énement | Niveau, domaine | mechanism |
|---|---|---|---|
| Une erreur JavaScript fatale, comme un throw dans un timer ou un gestionnaire d'événement | app_crashed | critical, diagnostics | js_fatal |
| Une erreur de rendu qu'aucune error boundary n'a interceptée | app_crashed | critical, diagnostics | react_render |
Une erreur non fatale remontée à ErrorUtils | exception, handled: false | error | js_error |
| Un rejet de promesse non géré | exception, handled: false | error | unhandled_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).
Consentement
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 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
| Option | Par défaut | Rôle |
|---|---|---|
apiKey | La clé d'ingestion du projet, lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | Où vont les événements |
consent | granted | granted, pending ou denied |
environment | détecté | N'importe quel nom |
platform | ios / android | Quelle partie du produit envoie |
minimumLevel | debug | Les niveaux inférieurs sont écartés |
flushIntervalMs | 15000 | La fréquence d'envoi des événements en file au premier plan |
sessionTimeoutMs | 30 minutes | Une nouvelle session après ce délai sans événement |
maxDiskBytes | 20 MB | Ce qui peut attendre sur l'appareil ; les plus anciens partent en premier |
redactKeys | DEFAULT_REDACT_KEYS | Les clés d'attributs et de payload dont les valeurs sont remplacées. Votre liste remplace celle par défaut ; [] désactive le masquage |
captureErrors | true | Les erreurs JavaScript que personne n'a interceptées |
captureCrashes | true | Les plantages natifs |
attachScreen | true | L'attribut screen sur chaque événement |
attest | true | App Attest et Key Attestation |
mirrorToNativeLog | false | Affiche 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 stopAprès close, init peut être rappelée.