Sentry React Native: 2026 との統合ガイド

ローカルでReact Nativeアプリが動作していることが確認でき、QAも承認したあと、実際の運用に近づいたところで、必ずしも起こり得る質問が飛び込んでくる。

センチュリーがなければ、答えは通常よくありません。サポートチケット、曖昧なスクリーンショット、開発ビルドからコンソールログ、実行環境と一致しないものなどが返されます。センチュリー React Native を正しく設定すると、エラー、スタック、リリース情報、問題を解決するための十分なコンテキストが提供されます。ただし、 基本的なインストールは簡単な部分です。痛みは後で始まる:ネイティブ統合、シンボリック化、ソースマップ、リリース名付け、そしてライブアップデートを含む配信モデルで、すべてを整合させることができる。

CIやApp Storeのビルド、Androidのリリース、元のバイナリから来ないJavaScriptのバンドルなど、実際のセットアップはCIを乗り切る必要があります。

目次

• Sentry SDKの始め方
  • Capgoをインストールする前に必要なもの
  • ワイザードを実行して結果を確認する
• ネイティブiOSとAndroidプロジェクトの設定
  • iOSで何が変わったか
  • Androidで何が変わったか
  • ネイティブセットアップは後で時間を節約する
• リリースとソースマップの自動化
  • 実際に失敗する手動アップロードの理由
  • 実際に機能するリリースプロセス
  • CIスクリプトの実践的なパターン
• パフォーマンスデータとカスタムイベントのキャプチャ
  • __CAPGO_KEEP_0__
  • エラーの有用なコンテキストを追加
• __CAPGO_KEEP_0__
  • 安全にテストイベントをトリガー
  • Sentry UIで確認する必要があるもの
  • Sentry React Nativeの一般的なトラブルシューティング
• Capgoとライブアップデートワークフローの統合
  • ライブバンドルのリリース識別子をマッチング

Sentry SDKの初心者ガイド

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

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

通常のReact Native開発環境が必要です。Node、パッケージマネージャー、iOSとAndroidのプラットフォームツール、macOSの場合、Watchmanも必要です。また、SentryアカウントとReact Native用のプロジェクトを作成することも必要です。

If you’re still evaluating whether React Native is the right operational choice for your team, this React Native guide for businesses provides useful non-marketing context around platform trade-offs, staffing, and maintenance expectations. It’s worth reading before you commit your monitoring and release process around a shared codebase.

Install the SDK with the wizard from the project root:

npx @sentry/wizard@latest -i reactNative

The wizard asks a few things that developers often click through too quickly:

• Project selection. Please select the actual Sentry project you intend to use in production, not a temporary sandbox you’ll forget to update later.
• Native changes. Please select yes. JavaScript-only error capture is not enough for mobile apps.
• Optional features. Please turn on what you know you’ll use, but don’t enable everything blindly on day one if your team won’t review the resulting data.

Running the wizard and reviewing the result

After the wizard finishes, inspect the changes instead of trusting them without review. You should see a Sentry package in package.json, native changes under ios と android, and an initialization block in your app entry file.

A typical initialization looks like this:

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

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

The DSN tells the SDK where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment.

__CAPGO_KEEP_0__ に It tells the code where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment.

A practical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. If you’re also working through startup polish, this guide to "React Native splash screen setup" is useful because startup __CAPGO_KEEP_0__ order often intersects with where teams place Sentry initialization."Practical rule: アプリ起動の早い段階でSentryを初期化することをお勧めします。ナビゲーション、認証の水増し、リモート設定の後まで待つと、起動時のエラーを捉えることができなくなります。

この段階では、完璧さを追求する必要はありません。すぐにアプリをリリースし、後でこの記事でJavaScript例外をトリガーし、Sentryにイベントが到達していることを確認することが目標です。そうすることで、ネイティブとリリース層の理解が容易になります。

ネイティブiOSおよびAndroidプロジェクトの設定

この段階では、多くのReact Nativeチームが完了の錯覚に陥ります。JavaScriptSDKがインストールされ、イベントが表示され、クラッシュレポートが完了したと考えられますが、実際にはそうではありません。ネイティブ統合がオフの場合、最も重要なクラッシュがSentryに到達することはできません。

iOSで何が変わったか

iOSプロジェクトを開いて、ウィザードが変更した内容を確認してください。ベアReact Nativeアプリの場合、通常はアプリ起動とビルドフェーズの周りで変更が見つかります。Sentryの初期化ハンドラーとアップロードステップをビルドプロセスに関連付けていることを確認してください。

Xcodeで確認する場所

• アプリデリゲートの起動codeアプリは起動時早くSentryの初期化が必要です。
• ビルドフェーズデバッグシンボルやソースマップの処理に関連するSentryのアップロードスクリプトを探してください。
• ビルド設定とアーカイブの動作. Symbol files must be generated and available during archive builds.

アプリが AppDelegate.mmを使用している場合、初期化はよくReact Native ブリッジのブートストラップに近い位置にあります。

React Native のバージョン、テンプレート、および新しいアーキテクチャを使用しているかどうかに関係なく、ファイルの内容は異なる可能性があるため、ランダムなリポジトリからスニペットをコピーしないでください。プロジェクトの形状が一致する場合にのみします。

iOSネイティブのクラッシュにはシンボルデータが必要であり、アプリはクラッシュが観測できるようにSentryを開始する必要があります。

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

Androidで何が変わったか android/build.gradle, android/app/build.gradleAndroidでは通常、Gradleファイルの変更や、場合によってはマニフェストレベルでの設定変更が発生します。

を確認してください。

1. Gradleプラグインが適用されている リリースアーティファクトがビルド時で処理できるようにするためです。
2. バリアントハンドリングが正常である If you use product flavors or multiple build types.
3. ProGuard or R8の出力は考慮される If your release builds shrink or obfuscate code.

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

Nativeのセットアップチェックは、後で時間を節約する

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

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

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

通常はうまくいかないのは

最良の設定は、ネイティブの起動ハックが用意されている、ビルドスクリプトが毎回実行され、iOS、Android、JavaScript バンドルのリリース名が決定論的であることです。

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

Sentry React Native の設定が崩壊するのは、ここだけです。チームはSDKをインストールし、イベントを確認し、リリースの自動化を延期します。次に、最初の本格的な生産問題が発生し、スタックトレースが最適化され、リリースが欠落している、またはソースマップのアップロードが異なるバンドルのものであった場合です。

実践で手動アップロードが失敗する理由

失敗モードは予測可能です。

誰かが夜遅いホットフィックスの後、ソースマップをアップロードすることを忘れる

• アップロードされたファイルは、実行中のバイナリまたはOTAバンドルのコミットとは異なるものである ソースマップのアップロードは、異なるバンドルのものであった場合です。
• ソースマップのアップロードは、異なるバンドルのものであった場合です。 ソースマップのアップロードは、異なるバンドルのものであった場合です。
• iOS、Android、CIステップ間でリリース名が若干異なる。 マップアップロード後、再構築が発生し、Sentryが一致させるべき対象が無効化される。
• 「Notionでステップをドキュメント化する」アプローチは、緊急リリースがプレッシャーの中で出るまで機能するが、推奨しない。 React Native用のSentryリリースとソースマップの自動管理プロセスを示す7ステップのフローチャート。

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

リリースIDは一度生成され、全ての場所で再利用される。

ビルド、バンドル、アップロードステップは同じパイプラインで実行される。

• CIからソースマップがアップロードされる。 __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__.
• __CAPGO_KEEP_0__開発者用パソコンではなく、
• アプリはSentryにリリース文字列と同じ文字列を使用して初期化します。 CIがアップロード中に使用した文字列と同じリリース文字列です。

最後の点は、一般的に予想されるよりも多く重要です。Sentryにソースマップが必要だけではありません。 アプリが実行時に発行される正確なリリース識別子にソースマップを付属させる必要があります。.

チームがすでにモバイル自動化を標準化している場合、このガイド 自動ビルドとリリースワークフローとGitHub Actionsの CIスクリプトの実践的なパターン

CIでスクリプトを使用し、パイプライン環境から値をフィードします。

Android用のバンドルコマンドを適応させる必要があり、多くのチームはプラットフォーム固有のジョブを分割するのではなく、1つのスクリプトで両方を強制するのではなく、どちらも問題ありません。

#!/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"

一貫性が重要です。

リリースの規律は、巧妙なスクリプトよりも重要です。 CIを使用してアプリをビルドする際に、1つの命名規則をインジェクトし、ローカルなアドホックアップロードとCIの競合を防ぎましょう。

React Nativeの場合、リリース文字列を1つのビルド生成された設定場所に格納し、ビルド時に読み込むことをおすすめします。 Sentry.init():

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

結果は簡単です。イベントが到着すると、Sentryはminified frameをcodeにマップし、codeにマップするのではなく、実際に送信したものにマップします。

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

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

一般的なレポートは次のようになります：“ダッシュボードが遅い。” ただし、これだけではデバッグには十分ではありません。遅いのはどこですか？ナビゲーション中ですか？データの取得中ですか？重いチャートをレンダリング中ですか？Sentryは、エラーのインボックスとして扱わないようになり、実行中のアプリの挙動をインストルメントするようになります。

遅い画面をトレースするのではなく、推測するのではなく

パフォーマンストレースを初期化時に有効にし、実際のデバイスで問題を再現することで始めましょう。サンプリング戦略は環境と容量耐性に依存しますが、構造は次のようになります：

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

React Navigationを使用している場合、画面のトランジションがトレースデータを生成するように統合してください。次に、物理デバイスで問題を再現し、シミュレータでは隠されるようなユーザーが感じるような遅さを確認してください。

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

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

直感に頼ることよりも、実際に改善された結果が得られることを実感できます。

ウェブビューまたはハイブリッドアプリの監視パターンについて幅広く考えるチームにとって、この performance monitoring in Capacitor projects についての記事は読む価値があります。オペレーショナルマインドセットは似ていますが、スタックは異なります。

エラーに役立つコンテキストを追加する

イベントにビジネス上のコンテキストを含めることで、パフォーマンスデータがより役立つようになります。ただし、虚偽のメタデータではありません。ただ、影響を受けたユーザー、ユーザーがどの画面にいたか、そしてエラーが発生した直前に何が起こったかを判断できるだけの情報を含めます。

これらのツールを意図的に使用する

• ユーザー情報 とともに、サポートは報告を関連付けることができるため、特定のアカウントに影響を受けることを確認する必要がなくなる。 Sentry.setUser() パンくず
• タップして送信する、モーダルを開く、またはシンクを開始するなどのアクション用 カスタムタグ
• 計画タイプ、機能フラグの状態、または__CAPGO_KEEP_0__地域などの寸法用 for dimensions like plan type, feature flag state, or API region.
• 例外をキャッチして再スローしたり、制御されたエラーを表面化したりするとき 例えば

パンくずのトレイルは、”アプリがフリーズした”と”ダッシュボードを開き、シンクを開始し、古いリクエストを再試行した”と言うのと大きな違いになる。

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

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

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

for actions like tapping submit, opening a modal, or starting a sync.

You should verify Sentry before shipping, after build pipeline changes, and after SDK upgrades.

「いまでもうかいた」は意味のあるテストではありません。

JavaScriptとネイティブパスの両方で制御されたエラーをトリガーし、Sentryに到着する方法を調べるのが一番の手段です。

A male software developer writing __CAPGO_KEEP_0__ on a computer monitor with a test integration checklist on his desk.

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

開発者がコンピュータモニターにテスト統合チェックリストを置きながら、__CAPGO_KEEP_0__を書いている男性。

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

Native crash testing should be done carefully and only in development or controlled QA builds. The exact helper methods available can vary by SDK version and platform wiring, so I prefer using the SDK’s documented native crash test utility when present rather than inventing your own crash path.

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

For a JavaScript error, add a temporary button in a non-production screen:

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

• For a captured exception that won’t crash the app:アプリがクラッシュしない捕捉された例外の場合、以下の手順に従ってください。
• リリースとdist. ソースマップとシンボリケーションがずれます。
• スタックフレーム. 正しくアップロードされたJavaScriptマップの場合、読みやすいソースロケーションが表示されます。
• パンくずとタグ. カスタムコンテキストが正常に到着したことを確認します。
• 環境. 開発と実稼働イベントが混在して一つのストリームにしないようにします。

ネイティブイベントが到着したが、シンボリケーションが悪い場合は、アプリを code につきつけてはなりません。 それは通常、ビルドアーティファクトの問題です。

CapacitorのSentry React Nativeトラブルシューティング

リリースプロセスで常に小さな「監視スモークテスト」チェックリストを維持することは有効な習慣である。ステージングで1つのJSイベントをトリガーし、リリース値を確認し、ソースの場所を確認し、ビルドをプロモートする前にビルドを確認する

Live Updateワークフローと統合するCapgo

Live Updateがリリースモデルを変更する。ストア内のバイナリは同じままなのに、JavaScriptバンドルが下のほうで変更される。Sentryが元のアプリバージョンのみで考える場合、スタックトレースはすぐに誤解を招く

__CAPGO_KEEP_0__は、ライブバンドルのみに従うのではなく、ネイティブバイナリにも従うようにする必要があります。 ライブバンドルとネイティブバイナリのリリース識別子をマッチングするライブアップデートワークフローでは、

と

を、配信されたJavaScriptパッケージに紐付いたランタイム識別子として扱う必要があります。ネイティブアプリのバージョンはまだ重要ですが、バンドルが独立して変更できるようになったら、それだけでは十分ではありません。 release 実用的パターンは次のようになります。 dist ネイティブアプリのバージョンをベースのリリース名の一部として使用します。

ライブアップデートバージョンまたはパッケージ識別子を追加します。

• をチャネルまたはビルド固有の区別に使用します。
• そのモデルに合った場合、チャネルまたはビルド固有の区別に使用します。
• ライブアップデートワークフローでは、配信されたJavaScriptパッケージに紐付いたランタイム識別子として扱う必要があります。ネイティブアプリのバージョンはまだ重要ですが、バンドルが独立して変更できるようになったら、それだけでは十分ではありません。 dist ライブアップデートワークフローでは、配信されたJavaScriptパッケージに紐付いたランタイム識別子として扱う必要があります。ネイティブアプリのバージョンはまだ重要ですが、バンドルが独立して変更できるようになったら、それだけでは十分ではありません。
• 各ライブバンドの下のその正確なリリース識別子にソースマップをアップロードしてください。

例えば、もしアプリが起動時にアップデートメタデータを読み込む場合、現在のアクティブバンドから値を取得してSentryを初期化するようにしてください。ただし、静的ビルド設定のみから値を取得するのではなく。

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

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

これは、OTAスタイルのワークフローに関係なく、どのワークフローでも重要です。もしOTAスタイルのワークフローの背後にある動作の詳細についての良い理解を得たい場合は、__CAPGO_KEEP_0__アプリのライブアップデートの動作についてのこの説明を参照してください。 how live updates work in Capacitor apps https://__CAPGO_KEEP_0__.app からスクリーンショット

主な間違いは、ポストストアアップデートのために同じ静的リリース文字列を繰り返すことです。もし複数のバンドルが同じSentryリリースを共有している場合、デバッグは再び推測に戻ります。

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__ Capgo is worth evaluating. It gives Capacitor teams a structured way to deliver live updates, target channels, control rollouts, and recover from bad releases quickly. Pair that with disciplined Sentry release naming and source map uploads, and you get a workflow where errors still point to the exact code users are running.