Sentry React Native: 2026年統合ガイド

ローカルで動作する React Native アプリができて、QA が承認したあと、生産準備ができたところで、突然の質問が来る。ユーザーのデバイスでアプリが壊れる時どうなるの?

Sentry があると、通常の答えは悪い。サポートチケット、曖昧なスクリーンショット、開発用ビルドのコンソールログが来る。Sentry React Native を正しく設定すると、エラー、スタック、リリース、そして問題を解決するのに十分なコンテキストが得られる。ただし、基本的なインストールは簡単な部分 基本的なインストールは簡単です。.

目次

Sentry を __CAPGO_KEEP_0__ で始める

• Getting Started with the Sentry SDK
  • ワイザードを実行して結果を確認する
  • ネイティブの iOS と Android プロジェクトを設定する
• iOS で何が変わったか
  • Table of Contents
  • Androidで何が変わったか
  • 後で時間を節約するために保存されるネイティブ設定のチェック
• リリースとソースマップの自動化
  • 実践でアップロードが失敗する理由
  • 実際に機能するリリースプロセス
  • CIスクリプトの実践的なパターン
• パフォーマンスデータとカスタムイベントのキャプチャ
  • 遅い画面のトレースではなく、推測せずに
  • エラーに役立つコンテキストを追加
• 統合の検証とトラブルシューティング
  • 安全にテストイベントをトリガーする
  • Sentry UIで確認すること
  • 一般的なSentry React Nativeトラブルシューティング
• Live UpdateとCapgoのワークフローとの統合
  • ライブバンドルのリリース識別子をマッチングする

Sentry SDKの導入

Sentry React Nativeを新しいアプリケーションに導入する最速の方法は依然としてインストールウィザードです。ウィザードは、繰り返し設定のほとんどを処理し、迅速に機能する基準を達成します。そうすることが重要です。最初のインストールを手動で実行すると、初期プロダクションクラッシュまで、気づかれないようにする小さな不一致が生じることがよくあります。

インストールする前に必要なもの

通常のReact Native開発環境が必要です。Node、パッケージマネージャー、iOSとAndroidのプラットフォームツール、macOSの場合、Watchmanが既にワークフローの一部である場合など。SentryアカウントとReact Native用のプロジェクトも必要です。

まだチームの運用上の選択肢としてReact Nativeが適しているかどうかを評価している場合は、 ビジネス向けのReact Nativeガイド プラットフォームのトレードオフ、人件費、メンテナンスの期待値について、非マーケティング的なコンテキストを提供します。これを読む価値があります。監視とリリースプロセスを共有コードベースにコミットする前に。

ウィザードからプロジェクトルートでSDKをインストールします:

npx @sentry/wizard@latest -i reactNative

ウィザードは、開発者がよくスキップすることが多い質問をいくつかします:

• プロジェクトの選択. 生産環境で使用する予定のSentryプロジェクトを選択してください。 そうでない場合、更新を忘れてしまう可能性のあるテスト用のサンドボックスを選択してください。
• ネイティブの変更. モバイルアプリ用のJavaScriptのみのエラーキャプチャでは十分ではありません。
• オプションの機能. 使用することがわかっている機能を有効にしますが、チームが結果のデータを確認することなく、すべての機能を一挙に有効にするのではなく、最初の日は気をつけてください。

ワイザードの実行と結果の確認

. ワイザードが完了した後、変更を信頼するのではなく、確認してください。 Sentryパッケージが見つかります。 package.json, ネイティブの変更の下に ios と android、

アプリのエントリファイルに初期化ブロックが見つかります。

import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'YOUR_DSN',
});

The DSN SDK

DSNは、イベントを送信する場所を__CAPGO_KEEP_0__に教えています。 これは、必ずしも秘密の safe に保存する必要があるものとして扱うべきではありません。 これは、認証トークンと同じではありません。 ただし、環境設定をきれいに整理し、各環境で正しいSentryプロジェクトにアプリが指すようにすることが重要です。 A practical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. is useful because startup code order often intersects with where teams place Sentry initialization.

実践ルール: Sentryをアプリの起動時早く初期化することが重要です。ナビゲーション、認証、リモート設定の後に初期化すると、起動時のエラーを捕捉できません。

この段階では、完璧さを追求する必要はありません。すぐにアプリを起動し、後でこの記事で触れるようにJavaScriptの例外を発生させ、Sentryにイベントが送信されることを確認するだけです。そうすることで、ネイティブとリリースのレイヤーをより簡単に理解できます。

Native iOSとAndroidプロジェクトの設定

React Nativeチームでは、この段階で多くの人が完了と誤解を招くことがあります。JavaScriptのSDKがインストールされ、イベントが表示され、クラッシュレポートが完了したと考えられますが、実際にはそうではありません。ネイティブの統合がオフの場合、最も重要なクラッシュがSentryに送信されない可能性があります。

iOSで何が変わったか

iOSプロジェクトを開いて、ウィザードが変更した内容を確認してください。 React Nativeの基本的なアプリでは、通常、アプリ起動とビルドフェーズの周りで更新が行われます。 Sentryの初期化のハックとアップロードステップをビルドプロセスに関連付けていることを探しています。

In Xcode、次の場所を確認してください:

• アプリデリゲートの起動code. アプリは、起動の早い段階でネイティブのSentryの初期化が必要です。
• ビルドフェーズ. デバッグシンボルやソースマップの処理に関連するSentryのアップロードスクリプトを探してください。
• ビルド設定とアーカイブの動作. シンボルファイルはアーカイブビルドの際に生成され、利用可能でなければなりません。

アプリが使用している場合、初期化は通常、React Nativeのブリッジのブートストラッピングに近い位置にあります。 React Nativeのバージョン、テンプレート、そして新しいアーキテクチャを使用しているかどうかによって、ファイルの内容は異なる可能性があります。 したがって、プロジェクトの形状に合致するものでないリポジトリからスニペットをコピーしないでください。 AppDelegate.mm重要なのは、意図です: iOSのネイティブのクラッシュにはシンボルデータが必要であり、アプリはクラッシュが観測できるようにSentryを開始する必要があります。

iOSのクラッシュがSentryに表示されていて、読めないネイティブのフレームを持っている場合、問題は「Sentryが壊れている」ではなく、シンボルアップロードまたはリリースマッチングです。

iOS のクラッシュが Sentry に表示され、読めないネイティブ フレームが表示される場合、問題は「Sentry が壊れた」ことではありません。シンボルアップロードまたはリリースのマッチングが原因です。

Androidで何が変わったか

Androidでは、通常、Gradleファイルに変更が加えられ、時々、manifestレベルでの設定が行われます。確認してください android/build.gradle, android/app/build.gradle、そして、Sentry関連のプラグインやタスクのワイヤリング

確認するべき事項:

1. Sentry Gradle プラグインが適用されている リリースアーティファクトがビルド時で処理できるようにするため
2. バリアントハンドリングは正常 製品フラバーまたは複数のビルドタイプを使用する場合
3. ProGuardまたはR8の出力は、リリースビルドが縮小または不明性化される場合に考慮される リリースビルドが code を縮小または混乱させる場合。

Androidの一般的なミスは、ローカルデバッグ実行が成功したことから、リリース設定が正しいと仮定することです。それではありません。リリースパスは異なり、特に最適化とCI署名が含まれる場合に尤もです。チームが別々のデバッグ、ステージング、QA、ストアビルドを維持している場合、この モバイルビルドタイプの分解 は、各ビルドバリアントの監視動作を揃えるための便利なリファレンスです。

ネイティブのセットアップは、後で時間を節約するためのチェックです。

「ワイザードがファイルを変更した」だけでは止めないでください。直接動作を確認してください。

このチェックリストを使用してください。

• iOSビルドをローカルに保存してください シンボル処理中にビルドが失敗しないことを確認してください。
• リリース用のAndroidビルドを作成してください CIログを確認して、Sentry関連のタスクが正常に実行されていることを確認してください。
• パッケージ名とバンドル識別子マッピングをSentryで確認してください 複数のアプリを1つの組織で管理している場合
• リリースの命名規則を確認してくださいCIが不一致の名前のアーティファクトをアップロードする前に

ここではよく機能しないことの例です:

最良の設定は面白くありません。ネイティブ起動ハンドルは設定されています、ビルドスクリプトは毎回実行され、iOS、Android、JavaScript バンドルのリリース名は決定的です。

リリースとソースマップの自動化

Sentry React Nativeの設定が崩壊するのはここです。チームはSDKをインストールし、イベントを確認し、リリースの自動化を延期します。次に、最初の重大なプロダクション問題が発生し、スタックトレースがミニファイズされ、リリースが欠落したり、ソースマップのアップロードが異なるバンドルに属していたりします。

稼働頻度が低い場合、手動でソースマップをアップロードすることは許容されるかもしれません。実際には、人間は繰り返しリリースの帳簿管理に不十分です。

実際の運用では手動アップロードが失敗する理由

失敗のパターンは予測可能です:

• 誰かが深夜の緊急修正の後にアップロードを忘れる アップロードしたファイルは、実行中のバイナリまたはOTAバンドルとは異なるコミットに属します。
• リリース名はiOS、Android、CIステップの各ステップでわずかに異なります。 マップアップロード後にビルドが実行され、Sentryが一致させるべきものが無効化されます。
• リリース名が若干変更されます。 iOS、Android、CI ステップ間の差異。
• The failure modes are predictable: Someone forgets to upload maps

after a late-night hotfix.

実際に機能するリリースプロセス

信頼できるセットアップにはいくつかの特性があります。

• リリースIDは一度生成され、どこでも再利用されます。 ビルド、バンドル、アップロードのステップは同じパイプラインで実行されます。
• ソースマップはCIからアップロードされます、開発者用のノートパソコンからアップロードされません。.
• アプリは、CIがアップロード時に使用した同じリリース文字列でSentryを初期化します。最後の点は、よく期待されていません。Sentryにソースマップが必要だけではありません。アプリが実行時に発行した正確なリリース識別子に紐付けされたソースマップが必要です
• SentryのソースマップとReact Nativeのリリースの自動管理の7ステップフローチャートを示します。 実際に機能するリリースプロセス

信頼できるセットアップにはいくつかの特性があります。 リリースIDは一度生成され、どこでも再利用されます。.

あなたのチームがすでにモバイルの自動化を標準化している場合、このガイドは 自動ビルドとリリースワークフローとGitHubアクションの 同じ運用モデルに合っているでしょう。

実践的なCIスクリプトのパターン

CIでスクリプトを使うようにして、パイプライン環境から値を取得するようにしてください:

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

Android用のバンドルコマンドをアダプトする必要があります。また、多くのチームはプラットフォーム固有のジョブを分割するのではなく、両方のスクリプトを強制するのではなく、1つのスクリプトで両方を行うのではなく、どちらかを選択するのです。それでもかまいません。重要なのは一貫性です。

リリースの規律が優先される。 1つの命名規則を選択し、ビルド時にアプリに挿入し、CIとローカルなアドホックのアップロードが競合しないようにしてください。

React Nativeの場合、リリース文字列を1つのビルド生成された設定場所に格納し、ビルド時に読み込むようにしてください。 Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

結果は簡単です。イベントが到着したとき、Sentryは最小化されたフレームをcodeにマップすることができます。実際にcodeを出荷したと想定しているのとは異なります。

パフォーマンスデータとカスタムイベントのキャプチャ

クラッシュは何が壊れたかを教えてくれます。パフォーマンストレースはユーザーが諦めた前まで何が感じたかを教えてくれます。

Aの一般的な報告は次のようになります： “ダッシュボードは遅い。” それはデバッグには十分ではありません。遅いのはどこですか？ナビゲーション中ですか？データの取得中ですか？重いチャートをレンダリング中ですか？Sentryはここで役立ちます。エラーのインボックスとして扱うのではなく、アプリの動作をインストルメントするのを始めてください。

遅い画面を追跡するのではなく、推測するのではなく。

初めに、初期化時にパフォーマンストレースを有効にします。精度は環境と容量耐性に依存しますが、構造は次のようになります。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

React Navigationを使用する場合は、画面のトランジションがトレースデータを生成するように統合してください。物理デバイスで、シミュレータではありません。シミュレータはユーザーが気付くような遅さを隠します。

実用的なダッシュボードの例:

1. ユーザーがログイン後にメインダッシュボードを開きます。
2. ナビゲーションが完了しますが、コンテンツが遅れて表示されます。
3. トレースは画面のトランジションが長いことを示しています。
4. 子スパンは1つのAPIリクエストと1つの高コストのレンダーパスを示しています。
5. レンダーパスを最適化し、再度配信し、新しいトレースの形状を比較します。

それが、直感に頼るのではなく、より良い方法です。

webview またはハイブリッドアプリの監視パターンについて広く考えているチーム向け Capacitor プロジェクトにおけるパフォーマンス監視についてのこの記事 は、スタックが異なっていても、運用の視点は似ているため、読む価値があります。

エラーに有用なコンテキストを追加する

パフォーマンスデータは、イベントにビジネス上のコンテキストが含まれる場合にのみ、より有用になります。ただし、虚飾的なメタデータではありません。ただ、失敗の直前に何が起こったか、どの画面にいたか、そしてどのアカウントが影響を受けたかを答えるだけです。

これらのツールを意図的に使用してください:

• ユーザーコンテキスト with Sentry.setUser() ブレッドクラム
• Breadcrumbs カスタムタグ
• ユーザーコンテキスト 次元の例として、プランタイプ、機能フラグの状態、またはAPI地域。
• キャプチャされた例外と追加のコンテキスト キャッチして再投げる、または制御されたエラーを表面化するとき。

例:

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

ブレッドクラストレールは、ユーザーが「アプリがフリーズした」ということと、「アプリがダッシュボードを開き、シンクを開始し、古いリクエストを再試行した後、失敗した」ということの差を示すことがよくあります。

カスタムインストルメンテーションが間違った場合、通常は過度にノイズが高くなります。アプリのすべてのボタンを永久にキャプチャしないでください。デバッグするときに重要な境界、状態の移行、操作をキャプチャしてください。イベントを説明するのに十分なコンテキストを提供してください。イベントを溺死させるほど多くキャプチャしないでください。

統合を検証し、トラブルシューティングする

Capgoを出荷する前に、ビルドパイプラインの変更後、またはSDKのアップグレード後、Capgoを検証する必要があります。「数ヶ月前は動いた」ということは意味のあるテストではありません。

最もきれいな方法は、JavaScriptとネイティブの両方のパスで制御されたエラーをトリガーし、Sentryに到着する方法を調べることです。

テストイベントを安全にトリガーする

JavaScriptエラーの場合、非生産的な画面に一時的なボタンを追加してください:

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

アプリがクラッシュしないキャプチャ例外の場合:

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

ネイティブのクラッシュテストは、開発または制御されたQAビルドで慎重に実行する必要があります。具体的なヘルパーメソッドは、SDKのバージョンとプラットフォームのワイヤリングによって異なる可能性があるため、利用可能なヘルパーメソッドが異なる可能性があります。SDKのドキュメントされたネイティブクラッシュテストユーティリティを使用することをお勧めします。

Sentry UIで確認するもの

イベントが表示されたら、タイトルだけではなく、詳細を確認してください。

確認する項目

• プラットフォームとメカニズムJS例外とネイティブクラッシュを区別するために役立ちます。
• リリースとディストソースマップとシンボリケーションが正しく機能するためには、正しくアップロードされたJavaScriptマップのソースロケーションが表示される必要があります。
• スタックフレームソースマップが正しくアップロードされている場合、読み取り可能なソースロケーションが表示される必要があります。
• クレームとタグ.
• 環境.

原生イベントが到着するが、シンボリック化が不十分な場合は、さらにアプリを code を調整するのではなく、通常はビルドアーティファクトの問題です。

.

リリースプロセスで、確認リリース値とソースの場所を確認し、ステージングで1つのJSイベントをトリガーし、ビルドをプロモートする前に、監視の煙試験チェックリストを小さく維持することは最終的な習慣で効果がある

Live UpdateワークフローとCapgoの統合

ライブアップデートはリリースモデルを変える。ストア内のバイナリは同じままなのに、JavaScriptのバンドルが下の部分で変更される。Sentryは元のアプリバージョンだけを考慮しているとき、スタックトレースはすぐに誤解を招く

解決策は Sentryリリースのアイデンティティはライブバンドルに従う、バイナリのみではなく

ライブバンドルと一致するリリース識別子

live updateワークフローでは release と dist 実行時識別子としてJavaScriptパッケージが配信されたときに結びつく。

実践的なパターンは次のようになります。

• 実践的なパターンは次のようになります。
• Capgoでは、live updateバージョンまたはパッケージ識別子を追加します。
• Use dist チャネルまたはビルド固有の区別に使用します。
• アップロードソースマップをその特定のリリース識別子下にそれぞれアップロードします。

例えば、アプリが起動時にアップデートメタデータを読み込む場合、現在アクティブなバンドルから値を導き出してSentryを初期化します。静的ビルド構成のみからではなく。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

そのようにすると、ユーザーがホットフィックスされたバンドルでエラーを発生させると、Sentryはソースマップをホットフィックスのものではなく古いストアバンドルのものに解決します。

これは、OTAスタイルのワークフローに関係なく重要です。ホットフィックスされたバンドルでエラーを発生させると、Sentryはソースマップをホットフィックスのものではなく古いストアバンドルのものに解決します。 この動作モデルについての詳しい説明はCapacitorアプリの は堅実なリファレンスです。

ここでは、更新メタデータとリリーストラッキングを組み合わせた、チームが目指すような実行可能なビューが示されています。

主なミスは、ポストストアアップデートのために同じ静的リリース文字列を再利用することです。同一のSentryリリースを共有する複数のバンドルがある場合、デバッグはまたもや推測に戻ります。

あなたのチームがアプリストアのレビューサイクル外で修正を配布している場合、 Capgo は評価すべき価値があります。Capacitorチームに構造化された方法でライブアップデートを配布する、チャンネルをターゲットにする、ロールアウトを制御する、そして悪いリリースから迅速に回復することができます。Disciplined Sentryリリースの命名とソースマップのアップロードを組み合わせると、エラーはまだ、実行中のcodeユーザーに正確に指示します。