アーリーアクセス招待制です。SDK はまだ公開されていません。招待をリクエスト
本文へスキップ
ドキュメント

React Native

Swift と Android の SDK の上で、React Native アプリから構造化ログ、JavaScript のエラー、クラッシュを送ります。

iOS と Android のアプリ(ネイティブ SDK の上に構築)

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 install

iOS では、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-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、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_crashedcritical、diagnosticsjs_fatal
どのエラーバウンダリーも捕捉しなかったレンダリングエラーapp_crashedcritical、diagnosticsreact_render
ErrorUtils に報告された致命的でないエラーexception、handled: falseerrorjs_error
処理されなかった Promise の rejectexception、handled: falseerrorunhandled_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 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値を置き換える属性とペイロードのキー。指定したリストがデフォルトを置き換え、[] でオフになります
captureErrorstrue誰も捕捉しなかった JavaScript のエラー
captureCrashestrueネイティブのクラッシュ
attachScreentrueすべてのイベントに付ける screen 属性
attesttrueApp Attest と Key Attestation
mirrorToNativeLogfalseすべてのイベントを 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 stop

close のあとに、もう一度 init を呼べます。