Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

React Native

Logs estruturados, erros de JavaScript e crashes do seu app React Native, por cima dos SDKs de Swift e Android.

Apps iOS e Android, sobre os SDKs nativos

O SDK de React Native é um TurboModule fino por cima dos SDKs de Swift e Android. Os SDKs nativos mantêm a fila em disco, enviam em lotes, tentam de novo, mantêm as sessões e reportam os crashes nativos. Este pacote acrescenta o que só o JavaScript enxerga: erros não capturados, rejeições de promise não tratadas, erros de renderização do React e as telas do React Navigation.

Ele requer React Native 0.80 ou posterior com a New Architecture, e React 19. Os apps rodam no iOS 16 ou posterior e no Android 7.0 (API 24) ou posterior.

Prévia interna: este pacote ainda não foi publicado. Até lá, @lyrelog/react-native não está no npm, e os SDKs nativos sobre os quais ele é construído também não foram publicados.

Instalação

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

No iOS, o pod traz o pacote Swift Lyrelog pelo Swift Package Manager. Defina o deployment target do seu app (e a linha platform :ios do Podfile) como 16.0 ou posterior. No Android, o Gradle baixa com.lyrelog:lyrelog-android do Maven Central, que adiciona a permissão INTERNET.

Primeiros passos

Inicie uma única vez, o mais cedo possível, no index.js, antes do AppRegistry. Uma segunda chamada mantém a primeira configuração. Eventos registrados antes de init são ignorados, mas setUser e setConsent chamados antes de init são guardados e aplicados quando ele roda.

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

Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los para outro lugar. Ele precisa ser https; http simples só funciona para localhost, 127.0.0.1 ou ::1 (o simulador do iOS) e, no emulador do Android, para 10.0.2.2.

Nada no SDK lança exceções no seu app. Em um build de desenvolvimento, uma chave faltando ou um módulo nativo faltando (o app não foi recompilado depois da instalação) é avisado uma vez com console.warn.

Registrar eventos

Uma função por nível: 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 },
});

Os atributos são campos pequenos para filtrar e montar gráficos: strings, números, booleanos, null, arrays e objetos aninhados em até 4 níveis. O payload é qualquer JSON, para o detalhe que você só lê quando abre um evento. minimumLevel (padrão debug) descarta os níveis mais baixos antes que eles cheguem ao código nativo.

Loggers para cada área

Um logger marca a sua category em todo evento. Ele tem todos os níveis, além de log e captureException.

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

Usuários

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

Lyrelog.sessionId traz o id da sessão atual, por exemplo para mostrar em uma tela de suporte. O id do usuário não é salvo entre uma inicialização e outra: chame setUser de novo a cada inicialização.

Telas

Com o React Navigation, faça o spread de trackNavigation no 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>
  );
}

Cada tela exibida registra screen_viewed (área navigation) com screen, previous_screen e seconds_on_previous, e todo evento seguinte é marcado com um atributo screen. O nome é o da rota; passe name: (route) => ... para escolher outro, ou retorne undefined para ignorar uma rota. Os seus próprios onReady e onStateChange vão nas opções e rodam depois dos do Lyrelog.

Sem o React Navigation, chame Lyrelog.screen("Settings"), ou useLyrelogScreen("Settings") no componente da tela. Chamar screen de novo com o mesmo nome não registra nada. Desative a marcação com attachScreen: false.

Erros que você captura

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

Capturar uma exceção envia o evento exception que todo SDK envia: nível error, os atributos error_type e error_message, e um payload com o nome, a mensagem, a stack e até 3 causas (error.cause). attrs acrescenta os seus; level muda o nível. Em JavaScript, qualquer coisa pode ser lançada: uma string ou um objeto também são registrados.

As stacks são como o Hermes as informa. Em um build de release, elas apontam para dentro do bundle: guarde o source map do build para conseguir lê-las.

Erros que ninguém capturou

Com captureErrors (ativado por padrão), o SDK se conecta ao tratamento de erros do React Native:

O que aconteceEventoNível, áreamechanism
Um erro fatal de JavaScript, como um throw em um timer ou em um event handlerapp_crashedcritical, diagnosticsjs_fatal
Um erro de renderização que nenhum error boundary capturouapp_crashedcritical, diagnosticsreact_render
Um erro não fatal reportado ao ErrorUtilsexception, handled: falseerrorjs_error
Uma rejeição de promise não tratadaexception, handled: falseerrorunhandled_rejection

Um erro fatal é gravado em disco antes de o app fechar, esperando até 1,5 segundo, e é enviado nesse momento se possível; senão, na próxima inicialização. Ele é um app_crashed na área diagnostics, como os relatórios de crash nativos, para que os crashes de JavaScript e os nativos fiquem juntos no painel.

Cada erro é registrado uma vez. Erros não capturados que não são fatais têm um limite de 10 por minuto, e o mesmo erro no máximo uma vez a cada 10 segundos; Lyrelog.skippedErrors conta o que ficou de fora. Os handlers que já existiam continuam rodando: a tela vermelha e o LogBox em desenvolvimento, o crash em release.

Error boundaries

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

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

Um erro de renderização dentro do boundary é registrado como exception com mechanism: error_boundary e a component stack do React (component_stack no payload), e o fallback é exibido no lugar. onError é chamado depois do registro. Sem um fallback, ele não renderiza nada depois de um erro.

Crashes nativos

Ficam por conta dos SDKs nativos (captureCrashes, ativado por padrão), enviados na próxima inicialização na área diagnostics: no Android, as exceções da JVM não capturadas como app_crashed; no iOS, os relatórios do MetricKit, com crashes como app_crashed e travamentos como app_hung. Veja crashes no Android e crashes e travamentos no Swift.

No Android, um erro fatal de JavaScript encerra o app com uma exceção Java. Assim que o app_crashed do JavaScript está em disco, essa exceção é ignorada pelo registro do SDK de Android, para que o mesmo crash não seja reportado duas vezes.

Ambientes e plataforma

O ambiente é o do SDK nativo: no iOS, development em builds de debug, testflight no TestFlight, production nos outros casos; no Android, development quando o app é depurável, production nos outros casos. Os seus próprios builds de debug enviam development, enquanto o painel abre em production: escolha development na barra superior para vê-los.

A plataforma é ios ou android. Sobrescreva qualquer um dos dois:

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

Os eventos identificam este pacote e o SDK nativo por baixo dele (sdk é 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 mantém os eventos no dispositivo sem enviá-los. Nada é enviado a menos que o consentimento seja dado. O consentimento não é salvo entre uma inicialização e outra: guarde você mesmo a escolha da pessoa (por exemplo, com o AsyncStorage) e passe-a para init a cada vez.

Atestação

attest (ativado por padrão) prova o app com App Attest no iOS e Key Attestation no Android, para que os eventos sejam armazenados como verificados. Veja Eventos verificados.

Opções

OpçãoPadrãoO quê
apiKeyA chave de ingestão do projeto, lyr_ing_...
endpointhttps://ingest.lyrelog.comPara onde os eventos vão
consentgrantedgranted, pending ou denied
environmentdetectadoQualquer nome
platformios / androidQual parte do produto envia
minimumLeveldebugNíveis mais baixos são descartados
flushIntervalMs15000De quanto em quanto tempo os eventos na fila são enviados em primeiro plano
sessionTimeoutMs30 minutosUma nova sessão depois desse tempo sem nenhum evento
maxDiskBytes20 MBO que pode ficar esperando no dispositivo; os mais antigos saem primeiro
redactKeysDEFAULT_REDACT_KEYSChaves de atributos e do payload cujos valores são substituídos. A sua lista substitui os padrões; [] desativa a ocultação
captureErrorstrueErros de JavaScript que ninguém capturou
captureCrashestrueCrashes nativos
attachScreentrueO atributo screen em todo evento
attesttrueApp Attest e Key Attestation
mirrorToNativeLogfalseImprime também cada evento no console do Xcode ou no logcat

Esvaziar a fila e parar

Ir para segundo plano já esvazia a fila, então você raramente vai precisar fazer isso.

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

Depois de close, init pode ser chamado de novo.