React Native
Swift と Android の SDK の上で、React Native アプリから構造化ログ、JavaScript のエラー、クラッシュを送ります。
React Native SDK は、Swift と Android の SDK の上に載った薄い TurboModule です。キューをディスクに保持すること、バッチでの送信、再試行、セッションの管理、ネイティブのクラッシュの報告は ネイティブの SDK が行います。このパッケージが加えるのは、JavaScript からしか見えないものです。未捕捉のエラー、 処理されなかった Promise の reject、React のレンダリングエラー、React Navigation の画面です。
New Architecture を有効にした React Native 0.80 以降と、React 19 が必要です。アプリは iOS 16 以降と Android 7.0(API 24)以降で動きます。
社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは @lyrelog/react-native は npm になく、
その土台となるネイティブの SDK も公開されていません。
インストール
pnpm add @lyrelog/react-native
cd ios && pod installiOS では、pod が Swift Package Manager を通して Swift パッケージ Lyrelog を取り込みます。アプリのデプロイメント
ターゲット(と Podfile の platform :ios の行)を 16.0 以降にしてください。Android では、Gradle が Maven Central
から com.lyrelog:lyrelog-android を取得し、INTERNET パーミッションが追加されます。
開始
できるだけ早い段階で、index.js の AppRegistry より前で一度だけ開始します。2 回目の呼び出しでは最初の設定が
維持されます。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 で一度だけ知らせます。
イベントを記録する
レベルごとに関数が 1 つあります。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 階層までのネストした
オブジェクトが使えます。ペイロードは任意の JSON で、1 つのイベントを開いたときにだけ読む詳細のためのものです。
minimumLevel(デフォルトは debug)より低いレベルは、ネイティブコードに渡る前に破棄されます。
領域ごとのロガー
ロガーは、すべてのイベントに自分の 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-outLyrelog.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、previous_screen、seconds_on_previous を付けて screen_viewed
(領域 navigation)が記録され、以降のすべてのイベントに 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、
ペイロードには名前、メッセージ、スタック、最大 3 つの原因(error.cause)が入ります。attrs
で独自の属性を追加でき、level でレベルを変えられます。JavaScript では何でも throw できるので、文字列や
オブジェクトも記録されます。
スタックは Hermes が報告したとおりです。リリースビルドではバンドル内を指すので、読むにはビルドのソースマップを 保存しておいてください。
誰も捕捉しなかったエラー
captureErrors(デフォルトでオン)が有効なら、SDK は React Native のエラー処理にフックします。
| 起きたこと | イベント | レベル、領域 | mechanism |
|---|---|---|---|
| JavaScript の致命的なエラー(タイマーやイベントハンドラー内での throw など) | app_crashed | critical、diagnostics | js_fatal |
| どのエラーバウンダリーも捕捉しなかったレンダリングエラー | app_crashed | critical、diagnostics | react_render |
ErrorUtils に報告された致命的でないエラー | exception、handled: false | error | js_error |
| 処理されなかった Promise の reject | exception、handled: false | error | unhandled_rejection |
致命的なエラーは、アプリが終了する前に最大 1.5 秒待ってディスクに書き込まれ、可能ならその場で、無理なら次回の
起動時に送られます。ネイティブのクラッシュレポートと同じく diagnostics 領域の app_crashed なので、
JavaScript とネイティブのクラッシュがダッシュボードに並びます。
各エラーは 1 回だけ記録されます。致命的でない未捕捉のエラーは 1 分あたり 10 件までで、同じエラーは 10 秒に
1 回までです。Lyrelog.skippedErrors で除外された件数がわかります。もともとあったハンドラーはそのまま動きます。
開発中なら red box と LogBox、リリースならクラッシュです。
エラーバウンダリー
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>その下で起きたレンダリングエラーは、mechanism: error_boundary と React のコンポーネントスタック(ペイロードの
component_stack)を付けて exception として記録され、代わりに 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 の記録をスキップするので、同じクラッシュが 2 回報告されることは
ありません。
環境とプラットフォーム
環境はネイティブの SDK のものです。iOS ではデバッグビルドで development、TestFlight で testflight、それ以外は
production。Android ではアプリがデバッグ可能なら development、それ以外は production です。自分の
デバッグビルドは 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 recordingpending はイベントを送信せずにデバイスに保持します。同意が得られない限り、何もアップロードされません。同意は
起動をまたいで保存されません。ユーザーの選択は自分で保存し(たとえば AsyncStorage で)、毎回 init に渡してください。
Attestation
attest(デフォルトでオン)は、iOS では App Attest、Android では Key Attestation でアプリを証明し、その
イベントが検証済みとして保存されるようにします。検証済みイベントを参照してください。
オプション
| オプション | デフォルト | 内容 |
|---|---|---|
apiKey | プロジェクトのインジェストキー、lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | イベントの送信先 |
consent | granted | granted、pending、denied |
environment | 自動検出 | 任意の名前 |
platform | ios / android | プロダクトのどの部分が送るか |
minimumLevel | debug | これより低いレベルは破棄されます |
flushIntervalMs | 15000 | フォアグラウンドでキュー内のイベントを送る間隔 |
sessionTimeoutMs | 30 分 | イベントがこの時間ないと新しいセッションになります |
maxDiskBytes | 20 MB | デバイス上で待機できる量。古いものから捨てられます |
redactKeys | DEFAULT_REDACT_KEYS | 値を置き換える属性とペイロードのキー。指定したリストがデフォルトを置き換え、[] でオフになります |
captureErrors | true | 誰も捕捉しなかった JavaScript のエラー |
captureCrashes | true | ネイティブのクラッシュ |
attachScreen | true | すべてのイベントに付ける screen 属性 |
attest | true | App Attest と Key Attestation |
mirrorToNativeLog | false | すべてのイベントを Xcode のコンソールまたは logcat にも出力します |
フラッシュと停止
バックグラウンドに移るときに送信されるので、自分で行う必要はほとんどありません。
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stopclose のあとに、もう一度 init を呼べます。