抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

React Native

从你的 React Native 应用收集结构化日志、JavaScript 错误和崩溃,基于 Swift 和 Android SDK。

iOS 和 Android 应用,基于原生 SDK

React Native SDK 是构建在 Swift 和 Android SDK 之上的一层轻量 TurboModule。原生 SDK 负责把队列保存在磁盘上、批量发送、重试、维护会话以及上报原生崩溃。这个包补上只有 JavaScript 才能看到的部分:未捕获的错误、未处理的 promise 拒绝、React 渲染错误以及 React Navigation 的页面。

它需要启用了新架构(New Architecture)的 React Native 0.80 或更高版本,以及 React 19。应用需运行在 iOS 16 或更高版本、Android 7.0(API 24)或更高版本上。

内部预览:这个包还没有发布。在发布之前,npm 上没有 @lyrelog/react-native,它所依赖的原生 SDK 也都还没有发布。

安装

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

在 iOS 上,这个 pod 会通过 Swift Package Manager 引入 Swift 包 Lyrelog。请把应用的 deployment target(以及 Podfile 中的 platform :ios 一行)设为 16.0 或更高。在 Android 上,Gradle 会从 Maven Central 拉取 com.lyrelog:lyrelog-android,该依赖会添加 INTERNET 权限。

启动

只启动一次,越早越好,放在 index.js 中 AppRegistry 之前。第二次调用会保留第一次的配置。在 init 之前记录的事件会被忽略,但在 init 之前调用的 setUser 和 setConsent 会被保留,并在启动时生效。

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

事件发送到 https://ingest.lyrelog.com。只有要发送到其他地方时才需要传 endpoint。它必须是 https;普通 http 只适用于 localhost、127.0.0.1 或 ::1(iOS 模拟器),以及 Android 模拟器上的 10.0.2.2。

SDK 不会向你的应用抛出任何异常。在开发构建中,缺少密钥或缺少原生模块(安装后没有重新构建应用)时,会用 console.warn 报告一次。

记录事件

每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者 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 },
});

属性是用于筛选和绘制图表的小字段:字符串、数字、布尔值、null、数组以及最多 4 层的嵌套对象。payload 可以是任意 JSON,用来放那些只有打开单个事件时才会看的细节。minimumLevel(默认 debug)会在跨越到原生代码之前丢弃更低级别的事件。

按分类使用 logger

logger 会在每个事件上打上它的 category。它有所有级别,外加 log 和 captureException。

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

用户

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

Lyrelog.sessionId 返回当前的会话 id,例如可以显示在客服支持页面上。用户 id 不会在两次启动之间保存:每次启动时再调用一次 setUser。

页面

使用 React Navigation 时,把 trackNavigation 展开到容器上:

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

每显示一个页面都会记录 screen_viewed(分类 navigation),带有 screen、previous_screen 和 seconds_on_previous,之后的每个事件都会打上 screen 属性。名称取自路由;传入 name: (route) => ... 可以换成别的名称,返回 undefined 则跳过该路由。你自己的 onReady 和 onStateChange 放在选项里,会在 Lyrelog 的之后运行。

不使用 React Navigation 时,调用 Lyrelog.screen("Settings"),或在页面组件中调用 useLyrelogScreen("Settings")。用相同的名字再次调用 screen 不会记录任何内容。用 attachScreen: false 可以关闭这种标记。

你捕获的错误

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

它发送的是每个 SDK 都会发送的 exception 事件:级别为 error,带有属性 error_type 和 error_message,payload 中包含名称、消息、调用栈以及最多 3 层 cause(error.cause)。attrs 用于添加你自己的属性;level 用于修改级别。JavaScript 可以抛出任何值:字符串或对象也同样会被记录。

调用栈保持 Hermes 报告的原样。在 release 构建中,它们指向打包后的 bundle:请保留该构建的 source map 以便解读。

没人捕获的错误

开启 captureErrors(默认开启)时,SDK 会接入 React Native 的错误处理:

发生了什么事件级别、分类mechanism
JavaScript 致命错误,例如在定时器或事件处理函数中抛出app_crashedcritical、diagnosticsjs_fatal
没有被任何 error boundary 捕获的渲染错误app_crashedcritical、diagnosticsreact_render
报告给 ErrorUtils 的非致命错误exception、handled: falseerrorjs_error
未处理的 promise 拒绝exception、handled: falseerrorunhandled_rejection

致命错误会在应用退出前写入磁盘(最多等待 1.5 秒),能发送时当场发送,否则在下次启动时发送。它是 diagnostics 分类中的 app_crashed,与原生崩溃报告一样,所以 JavaScript 崩溃和原生崩溃会并列显示在控制台中。

每个错误只记录一次。非致命的未捕获错误每分钟最多记录 10 个,同一个错误每 10 秒最多记录一次;Lyrelog.skippedErrors 统计被略过的数量。原有的 handler 仍会运行:开发时的红屏和 LogBox,release 中的崩溃。

Error boundary

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

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

其子树中的渲染错误会被记录为 exception,带有 mechanism: error_boundary 和 React 的组件栈(payload 中的 component_stack),同时改为显示 fallback。onError 会在记录之后被调用。没有 fallback 时,出错后它什么都不渲染。

原生崩溃

这部分由原生 SDK 负责(captureCrashes,默认开启),在下次启动时发送,位于 diagnostics 分类:Android 上未捕获的 JVM 异常记为 app_crashed;iOS 上来自 MetricKit 的报告,崩溃记为 app_crashed,卡顿记为 app_hung。见 Android 崩溃和 Swift 崩溃和卡顿。

在 Android 上,JavaScript 致命错误会以一个 Java 异常结束应用。一旦 JavaScript 的 app_crashed 已写入磁盘,这个异常就会绕过 Android SDK 的记录器,因此同一次崩溃不会被报告两次。

环境和平台

环境由原生 SDK 决定:iOS 上 debug 构建为 development,TestFlight 上为 testflight,其他情况为 production;Android 上应用可调试时为 development,其他情况为 production。你自己的 debug 构建发送的是 development,而控制台默认打开 production:在顶部栏选择 development 才能看到它们。

平台为 ios 或 android。两者都可以覆盖:

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

事件会注明这个包以及它底层的原生 SDK(sdk 为 lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 或 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 会把事件保留在设备上而不发送。除非已获得同意,否则什么都不会上传。同意状态不会在两次启动之间保存:请自己保存用户的选择(例如用 AsyncStorage),并在每次调用 init 时传入。

Attestation

attest(默认开启)在 iOS 上用 App Attest、在 Android 上用 Key Attestation 证明应用身份,这样它的事件会被保存为已验证事件。见已验证事件。

选项

选项默认值说明
apiKey项目的采集密钥,lyr_ing_...
endpointhttps://ingest.lyrelog.com事件发送到哪里
consentgrantedgranted、pending 或 denied
environment自动检测任何名称
platformios / android由产品的哪一部分发送
minimumLeveldebug更低的级别会被丢弃
flushIntervalMs15000前台时多久发送一次队列中的事件
sessionTimeoutMs30 分钟超过这么久没有事件,就开始新会话
maxDiskBytes20 MB设备上最多可以等待多少数据;最旧的先丢弃
redactKeysDEFAULT_REDACT_KEYS值会被替换的属性和 payload 键名。你的列表会替换默认值;[] 则关闭脱敏
captureErrorstrue没人捕获的 JavaScript 错误
captureCrashestrue原生崩溃
attachScreentrue每个事件上的 screen 属性
attesttrueApp Attest 和 Key Attestation
mirrorToNativeLogfalse同时把每个事件打印到 Xcode 的 console 或 logcat

立即发送(flush)和停止

进入后台时已经会自动发送,所以你很少需要手动立即发送。

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

调用 close 之后,可以再次调用 init。